Menu
POST agents/{public_id}/call-invite/ Service tier

POST /api/internal/v1/agents/<id>/call-invite/ {channel_public_id}

This read is not paginated. It returns at most 200 rows and does not report a total, so a result of exactly 200 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/call-invite/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
channel_public_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.

Responses

200 data and meta envelope

{
  "data": {
    "joined": true,
    "channel_public_id": "..."
  }
}

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

Errors

StatusCode
400channel_required
400invalid_json
400no_voice_profile
402no_credits
403agent_unavailable
409no_voice_key
409voice_key_invalid
409voice_key_unavailable
429voice_runtime_busy
502voice_runtime_refused
502voice_runtime_unreachable
503voice_runtime_draining
503voice_runtime_unset

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/call-invite/" \
  -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 '{
  "channel_public_id": "..."
}'

Source: MatterCore/voice_views.py (voice_views.agent_call_invite)

POST agents/{public_id}/call-leave/ Service tier

POST /api/internal/v1/agents/<id>/call-leave/ {channel_public_id}

Remove the agent's voice peer from a channel call. Same grant rule as the invite (the caller must be able to use the agent); idempotent : leaving a call the agent is not in is {left: false}, not an error.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/call-leave/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
channel_public_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.

Responses

200 data and meta envelope

{
  "data": {
    "left": "...",
    "channel_public_id": "..."
  }
}

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

Errors

StatusCode
400channel_required
400invalid_json
403agent_unavailable
502voice_runtime_unreachable
503voice_runtime_unset

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/call-leave/" \
  -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 '{
  "channel_public_id": "..."
}'

Source: MatterCore/voice_views.py (voice_views.agent_call_leave)

POST agents/{public_id}/call-review/ Service tier

POST /api/internal/v1/agents/<id>/call-review/ {call_id}

The post-call review: one run over the WHOLE transcript (including everything not addressed to the agent) that creates the tasks and updates that were agreed and posts one line to the channel. Runs inline in this request: the runtime calls it from a background thread on the VM, where nothing is CPU-throttled: and once per call: a second request for the same call reports the existing status.

This read is not paginated. It returns at most 300 rows and does not report a total, so a result of exactly 300 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/call-review/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
call_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.

Responses

200 data and meta envelope

{
  "data": {
    "status": "...",
    "call_id": "...",
    "run_id": "...",
    "note": "..."
  }
}

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

Errors

StatusCode
400call_required
400invalid_json
403agent_unavailable
404call_not_found

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/call-review/" \
  -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 '{
  "call_id": "..."
}'

Source: MatterCore/voice_views.py (voice_views.agent_call_review)

POST agents/{public_id}/call-transcript/ Service tier

POST /api/internal/v1/agents/<id>/call-transcript/ {channel_public_id, started_at, ended_at, turns:[{t, who, text, kind}]}

Sent by the voice runtime when the agent leaves a call. Posts the transcript to the channel AS the agent under its call_transcript policy, and writes a memory episode so the agent remembers the call.

This read is not paginated. It returns at most 4 rows and does not report a total, so a result of exactly 4 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/call-transcript/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
channel_public_idoptional or conditionalnone
ended_atoptional or conditionalnone
started_atoptional or conditionalnone
turnsoptional or conditionalnone
usageoptional 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.

Responses

200 data and meta envelope

{
  "data": {
    "posted": "...",
    "lines": 0,
    "policy": "...",
    "call_id": "...",
    "transcript_url": "...",
    "link_pushed": "...",
    "cost_cents": 0,
    "credits_billed": "...",
    "billing_status": "...",
    "review": "..."
  }
}

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

Errors

StatusCode
400channel_required
400invalid_json
403agent_unavailable

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/call-transcript/" \
  -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 '{
  "channel_public_id": "...",
  "ended_at": "...",
  "started_at": "...",
  "turns": "...",
  "usage": "..."
}'

Source: MatterCore/voice_views.py (voice_views.agent_call_transcript)

POST agents/{public_id}/voice-turn/ Service tier

POST /api/internal/v1/agents/<id>/voice-turn/

Body: {channel_public_id, transcript, speaker_name}. The acting email header must be the INVITER (the runtime echoes it from the join order) : that is who the turn bills to.

This read is not paginated. It returns at most 300 rows and does not report a total, so a result of exactly 300 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/voice-turn/

Path parameters

NameType
public_idstr

Query parameters

NameDefault
streamnone

Body keys (JSON)

KeyRequiredDefault
call_contextoptional or conditionalnone
channel_public_idoptional or conditionalnone
participantsoptional or conditionalnone
prioroptional or conditionalnone
speaker_nameoptional or conditionalnone
transcriptoptional 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.

Responses

200 non-JSON body

binary or text body

200 data and meta envelope

{
  "data": {
    "text": "...",
    "conversation_id": "...",
    "elapsed_ms": 0
  }
}

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

Errors

StatusCode
400invalid_json
400transcript_required
403agent_unavailable
502turn_failed

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/voice-turn/" \
  -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 '{
  "call_context": "...",
  "channel_public_id": "...",
  "participants": "...",
  "prior": "...",
  "speaker_name": "...",
  "transcript": "..."
}'

Source: MatterCore/voice_views.py (voice_views.agent_voice_turn)

GET call-transcripts/ Service tier

GET /api/internal/v1/call-transcripts/?channel=<public_id> [&started_at=<iso>&ended_at=<iso>][&limit=20]

Comms' fallback for linking a call card: the agent calls in this channel whose window overlaps the card's window (both bounds given), else the channel's most recent calls. Org-scoped by the caller.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/call-transcripts/

Query parameters

NameDefault
channelnone
ended_atnone
limitnone
started_atnone

Pagination

Accepts limit and offset and the server caps limit at 100. Check the response for a total or count field.

Responses

200 data and meta envelope

{
  "data": [
    {
      "call_id": "...",
      "agent_public_id": "...",
      "agent_name": "...",
      "channel_public_id": "...",
      "started_at": "2026-01-01T00:00:00Z",
      "ended_at": "2026-01-01T00:00:00Z",
      "duration_seconds": 0,
      "participants": [
        "..."
      ],
      "agent_lines": "...",
      "policy": "...",
      "transcript_url": "...",
      "usage": "...",
      "cost_cents": 0,
      "credits_billed": "...",
      "billing_status": "...",
      "review_status": "..."
    }
  ],
  "meta": {
    "count": 0
  }
}

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

Errors

StatusCode
400channel_required

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/call-transcripts/?channel=...&ended_at=...&limit=..." \
  -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/voice_views.py (voice_views.call_transcripts)

POST calls/{channel}/floor/claim/ Service tier

POST /api/internal/v1/calls/<channel>/floor/claim/ {agent_public_id, speaker_name, transcript, heard_at, addressed, claim_id?} -> {status: granted|wait|denied, claim_id, position, holder, prior, lease_s, reason}. Poll the same call (with claim_id) until granted or denied; a holder polling renews its lease.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calls/{channel}/floor/claim/

Path parameters

NameType
channelstr

Body keys (JSON)

KeyRequiredDefault
addressedoptional or conditionaltrue
agent_public_idoptional or conditionalnone
claim_idoptional or conditionalnone
depthoptional or conditionalnone
heard_atoptional or conditionalnone
originoptional or conditionalnone
speaker_nameoptional or conditionalnone
transcriptoptional 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.

Responses

200 data and meta envelope

{
  "data": "..."
}

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

Errors

StatusCode
400invalid_json
404agent_unknown

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/calls/CHANNEL/floor/claim/" \
  -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 '{
  "addressed": true,
  "agent_public_id": "...",
  "claim_id": "...",
  "depth": "...",
  "heard_at": "...",
  "origin": "...",
  "speaker_name": "...",
  "transcript": "..."
}'

Source: MatterCore/voice_views.py (voice_views.call_floor_claim)

POST calls/{channel}/floor/release/ Service tier

POST /api/internal/v1/calls/<channel>/floor/release/ {agent_public_id, claim_id, spoke, reply_text}

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calls/{channel}/floor/release/

Path parameters

NameType
channelstr

Body keys (JSON)

KeyRequiredDefault
agent_public_idoptional or conditionalnone
claim_idoptional or conditionalnone
reply_textoptional or conditionalnone
spokeoptional 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.

Responses

200 data and meta envelope

{
  "data": "..."
}

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

Errors

StatusCode
400invalid_json
404agent_unknown

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/calls/CHANNEL/floor/release/" \
  -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 '{
  "agent_public_id": "...",
  "claim_id": "...",
  "reply_text": "...",
  "spoke": "..."
}'

Source: MatterCore/voice_views.py (voice_views.call_floor_release)

GET voice-runtimes/ Service tier

GET /api/internal/v1/voice-runtimes/ : every known runtime with its live/stale status (ops + CI).

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/voice-runtimes/

Responses

200 data and meta envelope

{
  "data": [
    {
      "url": "...",
      "name": "...",
      "zone": "...",
      "version": "...",
      "max_calls": "...",
      "active_calls": "...",
      "free": "...",
      "draining": "...",
      "enabled": true,
      "status": "...",
      "uptime_s": "...",
      "age_s": "...",
      "first_seen_at": "2026-01-01T00:00:00Z",
      "last_seen_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "count": 0,
    "live": "...",
    "env_fallback": "..."
  }
}

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

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/voice-runtimes/" \
  -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/voice_views.py (voice_views.voice_runtimes_list)

POST voice-runtimes/heartbeat/ Service tier

POST /api/internal/v1/voice-runtimes/heartbeat/ (secret only; no org: a runtime serves every org). Body = fleet.describe() from the runtime: {url, name, zone, version, max_calls, active_calls, draining, uptime_s}. Upserts by url.

This read is not paginated. It returns at most 80 rows and does not report a total, so a result of exactly 80 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/voice-runtimes/heartbeat/

Body keys (JSON)

KeyRequiredDefault
drainingoptional or conditionalnone
nameoptional or conditionalnone
urloptional or conditionalnone
versionoptional or conditionalnone
zoneoptional 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.

Responses

200 data and meta envelope

{
  "data": {
    "registered": true,
    "created": true,
    "enabled": true
  }
}

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

Errors

StatusCode
400invalid_json
400url_required

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/voice-runtimes/heartbeat/" \
  -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 '{
  "draining": "...",
  "name": "...",
  "url": "...",
  "version": "...",
  "zone": "..."
}'

Source: MatterCore/voice_views.py (voice_views.voice_runtime_heartbeat)

All Agents resources
Start Free Explore our Products