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
Query parameters
| Name | Default |
collapse | none |
end | none |
start | none |
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
| Status | Code |
| 400 | invalid_range |
| 404 | agent_not_found |
| 405 | method_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
Body keys (JSON)
| Key | Required | Default |
action | optional or conditional | none |
cron_expression | optional or conditional | none |
id | optional or conditional | none |
knowledge_source_ids | optional or conditional | none |
max_invocations | optional or conditional | none |
model | optional or conditional | none |
name | optional or conditional | none |
preset | optional or conditional | none |
prompt | optional or conditional | none |
run_at | optional or conditional | none |
space_id | optional or conditional | none |
timezone | optional or conditional | none |
tool_names | optional or conditional | none |
variables | optional or conditional | none |
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
| Status | Code |
| 400 | invalid_max_invocations |
| 400 | invalid_schedule |
| 400 | name_required |
| 400 | prompt_required |
| 400 | unknown_action |
| 403 | manage_required |
| 404 | agent_not_found |
| 404 | schedule_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
| Name | Default |
collapse | none |
end | none |
start | none |
workspace | none |
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
| Status | Code |
| 400 | invalid_range |
| 405 | method_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)