Menu

Schedules

3 endpoints in the Mattering Agents API. Service tier only.

GET agents/{public_id}/calendar/ Service tier

GET ?start=&end=&collapse=1: one agent's schedules as calendar occurrences (one-offs, recurring projections, past runs). Read-only; Mattering Calendar's agent layer reads this (spec: planning/calendar-agent-schedules-spec.md).

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/calendar/

Path parameters

NameType
public_idstr

Query parameters

NameDefault
collapsenone
endnone
startnone

Responses

200 data and meta envelope

{
  "data": {
    "occurrences": "..."
  },
  "meta": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-01T00:00:00Z",
    "collapsed": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_range
404agent_not_found
405method_not_allowed

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/calendar/?collapse=...&end=...&start=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/agents_api.py (agents_api.agent_calendar)

GET agents/{public_id}/schedules/ Service tier

Read one of the schedules by id. derived from route

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/schedules/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
cron_expressionoptional or conditionalnone
idoptional or conditionalnone
knowledge_source_idsoptional or conditionalnone
max_invocationsoptional or conditionalnone
modeloptional or conditionalnone
nameoptional or conditionalnone
presetoptional or conditionalnone
promptoptional or conditionalnone
run_atoptional or conditionalnone
space_idoptional or conditionalnone
timezoneoptional or conditionalnone
tool_namesoptional or conditionalnone
variablesoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Pagination

Accepts limit and offset. The response meta carries total, limit and offset.

Responses

200 data and meta envelope

{
  "data": [
    {
      "id": "...",
      "name": "...",
      "cron_expression": "...",
      "run_at": "2026-01-01T00:00:00Z",
      "timezone": "...",
      "prompt": "...",
      "space_id": "...",
      "status": "...",
      "next_fire_at": "2026-01-01T00:00:00Z",
      "last_fire_at": "2026-01-01T00:00:00Z",
      "total_invocations": 0,
      "max_invocations": "...",
      "consecutive_errors": "...",
      "conversation_id": "...",
      "created_by_email": "...",
      "model": "...",
      "preset": "...",
      "variables": {
        "...": "..."
      }
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

200 data and meta envelope

{
  "data": {
    "id": "...",
    "name": "...",
    "cron_expression": "...",
    "run_at": "2026-01-01T00:00:00Z",
    "timezone": "...",
    "prompt": "...",
    "space_id": "...",
    "status": "...",
    "next_fire_at": "2026-01-01T00:00:00Z",
    "last_fire_at": "2026-01-01T00:00:00Z",
    "total_invocations": 0,
    "max_invocations": "...",
    "consecutive_errors": "...",
    "conversation_id": "...",
    "created_by_email": "...",
    "model": "...",
    "preset": "...",
    "variables": {
      "...": "..."
    }
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

200 data and meta envelope

{
  "data": {
    "deleted": true
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

201 data and meta envelope

{
  "data": {
    "id": "...",
    "name": "...",
    "cron_expression": "...",
    "run_at": "2026-01-01T00:00:00Z",
    "timezone": "...",
    "prompt": "...",
    "space_id": "...",
    "status": "...",
    "next_fire_at": "2026-01-01T00:00:00Z",
    "last_fire_at": "2026-01-01T00:00:00Z",
    "total_invocations": 0,
    "max_invocations": "...",
    "consecutive_errors": "...",
    "conversation_id": "...",
    "created_by_email": "...",
    "model": "...",
    "preset": "...",
    "variables": {
      "...": "..."
    }
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_max_invocations
400invalid_schedule
400name_required
400prompt_required
400unknown_action
403manage_required
404agent_not_found
404schedule_not_found

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/schedules/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/agents_api.py (agents_api.agent_schedules)

GET calendar/ Service tier

GET ?workspace=&start=&end=&collapse=1: every agent the caller can see (in the workspace, plus unbound ones), merged into one feed.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calendar/

Query parameters

NameDefault
collapsenone
endnone
startnone
workspacenone

Responses

200 data and meta envelope

{
  "data": {
    "occurrences": "..."
  },
  "meta": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-01T00:00:00Z",
    "collapsed": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_range
405method_not_allowed

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/calendar/?collapse=...&end=...&start=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/agents_api.py (agents_api.agents_calendar)

All Agents resources
Start Free Explore our Products