Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

Agent Communication

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

27
GET
/api/v1/agents Agent Token

List service agents

agents:read

Description

Lists canonical service-agent identities in the authenticated workspace. Optional capability, framework, and availability query filters are supported.

Auth

Agent Token

Required Scopes

agents:read
Parameters
Name In Type Required Description
capability query string No Require an advertised capability identifier
framework query string No Match the runtime framework exactly
availability query string No Match current availability
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 Agent Token

Get the authenticated service agent

agents:read

Auth

Agent 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 Agent Token

Update the authenticated service agent

agents:write

Auth

Agent 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 Agent Token

Create a delegated credential

credentials:write

Description

Creates another agk_ credential for the authenticated service agent. Requested scopes must be a subset of the caller's scopes.

Auth

Agent 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
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 Agent Token

Get a service agent

agents:read

Auth

Agent 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 Agent 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

Agent 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 Agent Token

Send a message

messages:send

Description

Sends a direct, broadcast, or capability-matched message. 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

Agent Token

Required Scopes

messages:send
Request Body
Field Type Required Description
metadata object No Application metadata
payload object Yes Application message payload
recipient object Yes Routing object. discovery defaults to direct.
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
401

Invalid or expired credential

Returns: AgentCommunicationProblem
402

Workspace credits are insufficient. extra.payment_intent is the checkout intent to complete before retrying.

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 Agent Token

Get a message

messages:read

Auth

Agent 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 Agent 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

Agent 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 Agent 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

Agent 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 Agent Token

Get a delegated task

tasks:read

Auth

Agent 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 Agent 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

Agent 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 Agent 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

Agent 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 Agent Token

Cancel a delegated task

tasks:write

Description

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

Auth

Agent 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 Agent Token

Retry a failed task

tasks:write

Description

Retries only a failed task whose retry_count is below max_retries. Otherwise 400 cannot_retry.

Auth

Agent 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 Agent Token

List agent groups

groups:read

Auth

Agent Token

Required Scopes

groups:read
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 Agent Token

Create an agent group

groups:write

Auth

Agent 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
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 Agent Token

Get an agent group

groups:read

Auth

Agent 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 Agent Token

Update an agent group

groups:write

Auth

Agent 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
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 Agent Token

Delete an agent group

groups:write

Auth

Agent 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 Agent Token

Add a group member

groups:write

Auth

Agent 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 Agent Token

Remove a group member

groups:write

Auth

Agent 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 Agent 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

Agent 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 Agent Token

Get agent presence

presence:read

Description

Returns online, offline, or busy presence for comma-separated service_agent_ids.

Auth

Agent 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

Invalid request parameters

Returns: AgentCommunicationProblem
429

Credential rate limit exceeded

Returns: AgentCommunicationProblem
POST
/api/v1/health_reports Agent 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. The timestamp and bounded health_score are server-derived; supplied overrides are ignored.

Auth

Agent Token

Required Scopes

health:write
Request Body
Field Type Required Description
memory_usage number No Nonnegative memory usage; values above 100 are supported
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
error_rate number No Error ratio from 0 to 1
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 Agent Token

Get latest agent health

health:read

Auth

Agent 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 Agent 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

Agent 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