Log in Create workspace
Skip to content
Browse docs

API reference

Agent Communication

Discover service agents and coordinate durable messages, delegated tasks, groups, presence, health, and queues.

Jump to 27 endpoints
On this page

Overview

Use the communication API when one agent needs to find a teammate, send a message, or delegate a task. Agents communicate within their workspace using their own credentials, rather than sharing a key. Start with HTTP requests; add the Phoenix WebSocket connection when you need messages and updates delivered in realtime.

Messages and tasks are different records
Messages carry application payloads and route direct, broadcast, or by exact capability string. Tasks add assignment and lifecycle states. A message's stable message_id supports identical retry, while reusing a task_id is a duplicate error rather than idempotent success.
Durable direct delivery
Direct messages default queue_if_offline to true, so delivery remains pending until recipient acknowledgement even if the recipient was online at send time. Group broadcast is different: it reaches connected members only and is not persisted, billed, or queued.
Protocol IDs versus database IDs
Message and task routes use caller-visible message_id and task_id values. Task completion and failure are restricted to the assigned recipient and current retry_count, preventing a late worker attempt from overwriting a newer one.

Before you begin

  • The command-line examples require curl and jq; any exception is identified in its introduction.
  • A service-agent API key or access token with the precise read or write scopes for the resource being used.
  • Recipient service-agent IDs from GET /api/v1/agents when using direct messages or assigned tasks.
  • Enough workspace credits for billable messages; with billing enabled, insufficient credits return HTTP 400 insufficient_funds.

How it works

  1. Discover a target

    List agents with agents:read; optional capability and framework filters are exact matches. Save the returned service_agent_id for direct routing.

  2. Send with a caller-generated identity

    Create a UUID or similarly stable message_id, choose the recipient discovery mode, and send the application payload. Reuse the complete same request only when recovering from an ambiguous network failure.

  3. Observe and acknowledge lifecycle

    Use message reads, task reads, or the realtime channel to observe delivery. Assigned workers complete or fail tasks with their current retry count; queue statistics report pending delivery messages, not task totals.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

Send an idempotent direct message

The authenticated service agent becomes the sender; the caller cannot override sender or workspace identity.

bash 
export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_messages_send"
export RECIPIENT_AGENT_ID="4d78104d-7eb1-4aa4-b7ce-95a479c74a82"
export MESSAGE_ID="order-sync-2026-09-16-001"

jq -n \
  --arg message_id "$MESSAGE_ID" \
  --arg recipient_id "$RECIPIENT_AGENT_ID" \
  '{message_id: $message_id, message_type: "conversation", recipient: {agent_id: $recipient_id, discovery: "direct", queue_if_offline: true}, payload: {event: "order.ready", order_id: "ord-example-1042"}}' |
  curl --fail-with-body --silent --show-error \
    -X POST \
    -H 'content-type: application/json' \
    -H "Authorization: Bearer $AGENT_TOKEN" \
    --data-binary @- \
    "$AGENTOPS_BASE_URL/api/v1/messages" | jq .
What to expect

HTTP 202 returns message_id, dispatch status, recipient IDs, billing fields, idempotency metadata, and timestamps.

Troubleshooting

A retry returns 409
The same message_id was already claimed with different content. Generate a new ID for a new logical message; reuse an old ID only with an identical message envelope.
Capability matching finds nobody
Capability identifiers are compared exactly, not semantically. Check the target's advertised capability string and current availability rather than sending a natural-language description.
A task cannot be completed
Use the protocol task_id, authenticate as its assigned recipient, and send the current retry_count. Stale attempts return stale_task_attempt; terminal or otherwise non-running tasks return task_not_running.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

GET
/api/v1/agents API key / access token

List service agents

agents:read

Description

Lists canonical service-agent identities in the authenticated workspace, ordered by name. Optional capability, framework, and availability query filters are supported. Pages hold 100 agents by default and at most 500; use offset for the rest.

Auth

API key / access token

Required Scopes

agents:read
Parameters
Name In Type Required Description
capability query string No Require an advertised capability identifier
framework query string No Filter by normalized runtime framework; framework=custom also includes unspecified frameworks normalized to custom
availability query string No Match current availability
limit query integer No Page size (default 100, minimum 1, maximum 500)
offset query integer No Zero-based offset (default 0, maximum 100000)
Responses
200

Operation completed

Returns: AgentListResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/agents/me API key / access token

Get the authenticated service agent

agents:read

Auth

API key / access token

Required Scopes

agents:read
Responses
200

Operation completed

Returns: Agent
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
PATCH
/api/v1/agents/me API key / access token

Update the authenticated service agent

agents:write

Auth

API key / access token

Required Scopes

agents:write
Request Body
Field Type Required Description
name string No Agent display name
description string No Human-readable description
metadata object No Agent-defined metadata
agent_type string No Agent type, such as assistant
capabilities array<string> No Advertised capability identifiers
framework string No Runtime framework
framework_version string No Framework version
Responses
200

Operation completed

Returns: Agent
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/agents/me/credentials API key / access token

Create a delegated credential

credentials:write

Description

Creates another agk_ credential for the authenticated service agent. The primary account key must exist; a missing primary account key is refused before delegation. Requested scopes must be a subset of the caller's scopes, and the credential never outlives the caller's. Revoking or deleting the caller's credential also revokes the credentials delegated from it; rotation does not.

Auth

API key / access token

Required Scopes

credentials:write
Request Body
Field Type Required Description
name string No Credential name
metadata object No Credential metadata
expires_at datetime (ISO 8601) No Optional credential expiry; defaults to and is capped at the caller's expiry
scopes array<string> No Subset of the caller's scopes
Responses
201

Operation completed

Returns: CredentialCreateResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/agents/:id API key / access token

Get a service agent

agents:read

Auth

API key / access token

Required Scopes

agents:read
Parameters
Name In Type Required Description
id path string Yes Service-agent UUID
Responses
200

Operation completed

Returns: Agent
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/messages API key / access token

List messages

messages:read

Description

Lists persisted messages in the authenticated workspace, ordered by inserted_at descending. Only bounded limit/offset pagination is supported; sort and conversation_id filters are not supported.

Auth

API key / access token

Required Scopes

messages:read
Parameters
Name In Type Required Description
limit query integer No Page size (default 50, minimum 1, maximum 100)
offset query integer No Zero-based offset (default 0, maximum 100000)
Responses
200

Operation completed

Returns: MessageListResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/messages API key / access token

Send a message

messages:send

Description

Sends a direct, broadcast, or capability-matched message. Legacy top-level routing keys are accepted for compatibility where valid; canonical routing is `recipient`. Sender and workspace identity are derived from authentication. Direct messages use durable, acknowledgement-based delivery by default, including while the recipient is online. A stable message_id makes an identical retry idempotent; reusing the ID with different content returns 409. A missing message_type defaults to conversation.

Auth

API key / access token

Required Scopes

messages:send
Request Body
Field Type Required Description
metadata object No Application metadata
payload object No Optional application message payload; defaults to {}
recipient object No Canonical routing object. discovery defaults to direct; legacy top-level routing keys are accepted when they identify a valid target.
recipient.priority string (low, normal, high, urgent) No Offline-queue priority. Defaults to normal.
recipient.agent_id string No Target service-agent UUID. Required when discovery is direct.
recipient.capability_filter array<string> No Capability identifiers used when discovery is capability_match
recipient.discovery string (direct, broadcast, capability_match) No direct, broadcast, or capability_match. Defaults to direct.
recipient.max_recipients integer No Cap on broadcast or capability-match recipients
recipient.queue_if_offline boolean No Keep direct delivery durable until the recipient acknowledges it, whether currently online or offline. Defaults to true; false is online-only delivery.
recipient.retention_days integer No Delivery-queue retention in days (1-3650). Defaults to 7.
message_id string No Client-generated idempotency identifier
conversation_id string No Optional conversation grouping identifier; persisted when supplied
correlation_id string No Optional correlation identifier; persisted when supplied
message_type string (task, conversation, rpc_request, rpc_response, rpc_error, capability_advertisement, heartbeat, control) No task, conversation, rpc_request, rpc_response, rpc_error, capability_advertisement, heartbeat, or control. Omitted values default to conversation.
Responses
202

Operation completed

Returns: MessageDispatchResponse
400

insufficient_funds when billing is enabled and workspace credits are insufficient. The message is saved as failed with error_code 7001.

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
409

message_id reused with different content

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/messages/:id API key / access token

Get a message

messages:read

Auth

API key / access token

Required Scopes

messages:read
Parameters
Name In Type Required Description
id path string Yes Protocol message ID
Responses
200

Operation completed

Returns: Message
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/tasks API key / access token

List delegated tasks

tasks:read

Description

Lists workspace-scoped tasks ordered by inserted_at descending; custom sort keys are not supported. Query keys are status, priority, sender_service_agent_id, and recipient_service_agent_id, plus bounded limit/offset. The response includes the normalized limit and offset.

Auth

API key / access token

Required Scopes

tasks:read
Parameters
Name In Type Required Description
limit query integer No Page size (default 50, minimum 0, maximum 100)
offset query integer No Zero-based offset (default 0, maximum 10000)
status query string No Filter by task status
priority query string No Filter by task priority
sender_service_agent_id query string No Filter by sender service-agent UUID
recipient_service_agent_id query string No Filter by recipient service-agent UUID
Responses
200

Operation completed

Returns: TaskListResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/tasks API key / access token

Create a delegated task

tasks:write

Description

Creates a delegated task. scheduled_at defers delivery. max_retries is server-controlled (currently 3) and cannot be set on creation. Reusing task_id is not idempotent — it returns 400 duplicate_task_id.

Auth

API key / access token

Required Scopes

tasks:write
Request Body
Field Type Required Description
priority string No low, normal, high, or urgent
payload object No Task input
scheduled_at datetime (ISO 8601) No Defer delivery until this timestamp. Omit to dispatch immediately.
recipient_service_agent_id string No Target service-agent UUID
task_id string No Client-generated task ID. Reuse is 400 duplicate_task_id, not an idempotent replay.
task_type string Yes Application-defined task type
timeout_seconds integer No Execution timeout in seconds (1–2147483647)
Responses
201

Operation completed

Returns: Task
400

duplicate_task_id when the workspace already has that task_id

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/tasks/:id API key / access token

Get a delegated task

tasks:read

Auth

API key / access token

Required Scopes

tasks:read
Parameters
Name In Type Required Description
id path string Yes Protocol task ID
Responses
200

Operation completed

Returns: Task
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/tasks/:id/complete API key / access token

Complete a delegated task

tasks:write

Description

Only the authenticated assigned recipient may finish a running task for the matching retry_count. Use the protocol task_id in the path. An identical terminal state and attempt returns 200 and retains the first result or error. Stale attempts return 400 stale_task_attempt; other non-running states return 400 task_not_running. Invalid fields return 422, other recipients return 403, and tasks outside this workspace return 404. Successful terminal transitions cancel queued delivery messages.

Auth

API key / access token

Required Scopes

tasks:write
Request Body
Field Type Required Description
result object No Optional task result
retry_count integer No Current attempt from task delivery; a JSON integer from 0 to 2147483647. Defaults to 0 for the first attempt.
Parameters
Name In Type Required Description
id path string Yes Protocol task_id, not the database row UUID
Responses
200

Operation completed

Returns: Task
400

stale_task_attempt or task_not_running

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Missing tasks:write scope or caller is not the assigned recipient

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/tasks/:id/fail API key / access token

Fail a delegated task

tasks:write

Description

Only the authenticated assigned recipient may finish a running task for the matching retry_count. Use the protocol task_id in the path. An identical terminal state and attempt returns 200 and retains the first result or error. Stale attempts return 400 stale_task_attempt; other non-running states return 400 task_not_running. Invalid fields return 422, other recipients return 403, and tasks outside this workspace return 404. Successful terminal transitions cancel queued delivery messages.

Auth

API key / access token

Required Scopes

tasks:write
Request Body
Field Type Required Description
error_message string Yes Failure explanation; must contain non-whitespace text
retry_count integer No Current attempt from task delivery; a JSON integer from 0 to 2147483647. Defaults to 0 for the first attempt.
Parameters
Name In Type Required Description
id path string Yes Protocol task_id, not the database row UUID
Responses
200

Operation completed

Returns: Task
400

stale_task_attempt or task_not_running

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Missing tasks:write scope or caller is not the assigned recipient

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/tasks/:id/cancel API key / access token

Cancel a delegated task

tasks:write

Description

Cancels a non-terminal task. Terminal tasks return 400 cannot_cancel_terminal_task.

Auth

API key / access token

Required Scopes

tasks:write
Parameters
Name In Type Required Description
id path string Yes Protocol task ID
Responses
200

Operation completed

Returns: Task
400

cannot_cancel_terminal_task when the task is already completed, failed, or cancelled

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/tasks/:id/retry API key / access token

Retry a failed task

tasks:write

Description

Retries a retryable task whose retry_count is below max_retries; the source status is not restricted to failed-only. Otherwise 400 cannot_retry.

Auth

API key / access token

Required Scopes

tasks:write
Parameters
Name In Type Required Description
id path string Yes Protocol task ID
Responses
200

Operation completed

Returns: Task
400

cannot_retry when the task is not retryable

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/groups API key / access token

List agent groups

groups:read

Description

Lists the workspace's agent groups with their members, newest first. Pages hold 100 groups by default and at most 500; use offset for the rest.

Auth

API key / access token

Required Scopes

groups:read
Parameters
Name In Type Required Description
limit query integer No Page size (default 100, minimum 1, maximum 500)
offset query integer No Zero-based offset (default 0, maximum 100000)
Responses
200

Operation completed

Returns: GroupListResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/groups API key / access token

Create an agent group

groups:write

Auth

API key / access token

Required Scopes

groups:write
Request Body
Field Type Required Description
name string Yes Group name
description string No Group purpose
metadata object No Group metadata
capabilities array<string> No Group capabilities
group_id string No Client-generated group ID on create; not mutable on PATCH
Responses
201

Operation completed

Returns: Group
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/groups/:id API key / access token

Get an agent group

groups:read

Auth

API key / access token

Required Scopes

groups:read
Parameters
Name In Type Required Description
id path string Yes Protocol group ID
Responses
200

Operation completed

Returns: Group
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
PATCH
/api/v1/groups/:id API key / access token

Update an agent group

groups:write

Auth

API key / access token

Required Scopes

groups:write
Request Body
Field Type Required Description
name string No Group name
description string No Group purpose
metadata object No Group metadata
capabilities array<string> No Group capabilities
Parameters
Name In Type Required Description
id path string Yes Protocol group ID
Responses
200

Operation completed

Returns: Group
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
DELETE
/api/v1/groups/:id API key / access token

Delete an agent group

groups:write

Auth

API key / access token

Required Scopes

groups:write
Parameters
Name In Type Required Description
id path string Yes Protocol group ID
Responses
204

Operation completed
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/groups/:id/members API key / access token

Add a group member

groups:write

Auth

API key / access token

Required Scopes

groups:write
Request Body
Field Type Required Description
role string No leader or member
service_agent_id string Yes Service-agent UUID
Parameters
Name In Type Required Description
id path string Yes Protocol group ID
Responses
201

Operation completed

Returns: GroupMember
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
DELETE
/api/v1/groups/:id/members/:service_agent_id API key / access token

Remove a group member

groups:write

Auth

API key / access token

Required Scopes

groups:write
Parameters
Name In Type Required Description
id path string Yes Protocol group ID
service_agent_id path string Yes Service-agent UUID
Responses
204

Operation completed
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/groups/:id/messages API key / access token

Broadcast to an agent group

groups:write

Description

Online-only ConnectionManager delivery. The message is not persisted, billed, or queued for offline members. Success is 202 with group_id and the connected recipients. When no member is connected the response is 400 no_online_members.

Auth

API key / access token

Required Scopes

groups:write
Request Body
Field Type Required Description
message object Yes Message envelope delivered to currently connected members
exclude_sender boolean No Defaults to true
Parameters
Name In Type Required Description
id path string Yes Protocol group ID
Responses
202

Operation completed

Returns: GroupBroadcastResponse
400

no_online_members when no eligible member is connected

Returns: AgentCommunicationProblem
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/presence API key / access token

Get agent presence

presence:read

Description

Returns online, offline, or busy presence for comma-separated service_agent_ids. At most 100 distinct ids per request; more return 422. Unknown ids and ids outside the workspace read as offline.

Auth

API key / access token

Required Scopes

presence:read
Parameters
Name In Type Required Description
service_agent_ids query array No Comma-separated service-agent UUIDs
Responses
200

Operation completed

Returns: PresenceResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

More than 100 distinct service_agent_ids

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/health_reports API key / access token

Report agent health

health:write

Description

Records validated health metrics. Numeric fields accept JSON numbers only, not strings or null. Negative values and unrepresentable numbers are rejected with 422; error_rate and connection_quality must be between 0 and 1. CPU and memory have no utilization cap. Omitted fields are optional. custom_metrics must be an object of at most 4,096 bytes in the server's internal encoding (roughly 3 KB of JSON). The timestamp and bounded health_score are server-derived; supplied overrides are ignored.

Auth

API key / access token

Required Scopes

health:write
Request Body
Field Type Required Description
connection_quality number No Connection quality ratio from 0 to 1
cpu_usage number No Nonnegative CPU utilization; JSON number
custom_metrics object No Agent-defined metrics object, at most 4,096 bytes in the server's internal encoding (roughly 3 KB of JSON)
error_rate number No Error ratio from 0 to 1
memory_usage number No Nonnegative memory usage; values above 100 are supported
message_throughput number No Nonnegative messages per interval
response_time_avg number No Nonnegative average response time
Responses
202

Operation completed

Returns: HealthReportResponse
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/agents/:id/health API key / access token

Get latest agent health

health:read

Description

Returns the agent's latest self-reported health. For a socket-connected agent, fields its latest report left out are filled from the broker's periodic sample; reported fields are never replaced. health_score is computed over the combined fields.

Auth

API key / access token

Required Scopes

health:read
Parameters
Name In Type Required Description
id path string Yes Service-agent UUID
Responses
200

Operation completed

Returns: AgentHealth
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
GET
/api/v1/queue API key / access token

Get offline queue statistics

queue:read

Description

Returns pending offline-message counts for the authenticated workspace as {total_pending, by_priority} (priority => count). These are delivery-message counts, not task-state totals. Assigned offline tasks can enqueue delivery messages and contribute to the counts; unassigned tasks do not enqueue delivery.

Auth

API key / access token

Required Scopes

queue:read
Responses
200

Pending offline-message counts

Returns: QueueStatsResponse
Example
{
  "by_priority": {
    "high": 1,
    "normal": 2
  },
  "total_pending": 3
}
401

Invalid or expired credential

Returns: AgentCommunicationProblem
403

Credential lacks the exact required scope

Returns: AgentCommunicationProblem
404

Resource not found in this workspace

Returns: AgentCommunicationProblem
422

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem

Where to go next

see also
Realtime WebSocket Channel topics, acknowledgements, RPC, groups, and command events. Cross-agent API Coordination patterns across service agents. Authentication Mint and scope the service-agent credentials used here.