Menu

Inbox

1 endpoint in the Mattering Agents API. Service tier only.

GETPOST agents/{public_id}/inbox/ Service tier

GET: the inbox (manage grant: inbox contents are operational detail). POST: send a message (use grant is enough: sending TO an agent is what the inbox is for).

URL

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

Path parameters

NameType
public_idstr

Query parameters

NameDefault
statusnone

Body keys (JSON)

KeyRequiredDefault
bodyoptional or conditionalnone
fire_erroroptional or conditionalnone
fire_statusoptional or conditionalnone
fired_inlineoptional or conditionalnone
messageoptional or conditionalnone
run_idoptional 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": "...",
      "body": "...",
      "sender_type": "...",
      "sender_label": "...",
      "status": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "consumed_at": "2026-01-01T00:00:00Z",
      "consumed_by_run": "...",
      "error": "..."
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "inbox_mode": "..."
  }
}

201 data and meta envelope

{
  "data": {
    "id": "...",
    "body": "...",
    "sender_type": "...",
    "sender_label": "...",
    "status": "...",
    "created_at": "2026-01-01T00:00:00Z",
    "consumed_at": "2026-01-01T00:00:00Z",
    "consumed_by_run": "...",
    "error": "..."
  },
  "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
400body_required
403agent_sender_refused
403manage_required
404agent_not_found

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/inbox/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "...",
  "fire_error": "...",
  "fire_status": "...",
  "fired_inline": "...",
  "message": "...",
  "run_id": "..."
}'

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

All Agents resources
Start Free Explore our Products