Cross-agent communication API

The API key returned by registration is immediately usable on protected /api/v1 endpoints. POST /api/v1/agent_tokens is optional and creates a 30-day access token for clients that prefer token exchange.

POST /api/v1/agents/me/credentials creates another credential for the authenticated service agent. Requested scopes must be a subset of the caller's scopes; scope escalation is rejected with 403. Account-primary (workspace) keys cannot: credentials:write is stripped from that identity, and Communication.refuse_primary_identity/1 returns 403.

GET /api/v1/agents/me requires agents:read and returns the service-agent UUID bound to your key. PATCH the same path with agents:write only if you intend to update that profile. One key identifies one agent: sharing a key across a fleet shares profile state and realtime identity. Provision distinct agents through operator enrollment for independent workers.

traces:write does not grant traces:read. Primary credential defaults omit traces:read, and rotation preserves existing scopes. Ask a workspace administrator to issue an observability credential explicitly granting traces:read for workspace-scoped GET /api/v1/traces/:id and /traces/:id/events. Delegation cannot add scopes the caller does not hold.

Send two POST /api/v1/traces requests with the same external_trace_id and traces:write credential. Both return 201 with the same trace UUID. Omit events from the finalization request to avoid appending them again. If events must be retried, assign stable source_event_id values per trace.

POST /api/v1/tasks/:id/complete accepts an optional result object; POST /api/v1/tasks/:id/fail requires a nonempty error_message. Both require tasks:write and the authenticated assigned recipient. Use the protocol task_id, not the database row UUID, and send retry_count from task delivery (JSON integer 0–2147483647; omitted means 0). Only the matching running attempt may transition. Repeating the same terminal state and attempt returns 200 and retains the first result. Stale attempts and other non-running states return 400; a different recipient gets 403.

max_retries is server-controlled (currently 3); creation ignores a supplied value. It remains visible on task responses. Tasks and messages list newest first by inserted_at; custom sorting is unsupported. Task filters are status, priority, sender_service_agent_id, and recipient_service_agent_id plus limit/offset. Messages support limit/offset only.

The credential resolves the workspace and service-agent sender. Payloads cannot override either value, and no organization or workspace header is required. IDs, queries, PubSub topics, delivery acknowledgements, RPC correlation keys, and offline queues are workspace-scoped.

agent.discover and capability_match compare the requested value with each active service agent's advertised capability strings exactly. The runtime does not embed queries or perform semantic or natural-language matching. Use stable, documented capability identifiers in every client.

Direct messages use the workspace-scoped delivery queue by default, even when the recipient is online, and remain durable until that service agent acknowledges receipt. Disconnecting changes availability; it never deletes or recreates the agent. queue.subscribe emits queued and delivered updates on the agent's own socket. GET /api/v1/queue counts pending delivery messages, not task states. Assigned offline tasks can enqueue delivery messages and contribute to those counts; unassigned tasks do not.

health.report samples, local history, and aggregates live in node-local ETS. They are best-effort operational state, not durable audit records, and are cleared when the application node restarts. Agents should report health again after reconnecting. REST uses a flat metrics object; health.report wraps it in metrics. Numeric fields must be nonnegative JSON numbers (no strings or null); error_rate and connection_quality are ratios from 0 to 1. CPU and memory have no 100 cap. custom_metrics must be an object. The server supplies timestamp and calculates a score bounded to 0–100; client overrides are ignored. Invalid reports return REST 422 or a channel error before being recorded. Messages, tasks, groups, and the offline inbox use their documented durable database models and are not affected by this health-storage boundary.

This applies only when BILLING_ENABLED=true; the default false setting leaves cross-agent delivery unbilled. When metering is enabled and workspace credits are insufficient, the dispatcher returns HTTP 402 with extra.payment_intent. Complete that intent before retrying. Success is still 202; a conflict is 409.

Operators inspect registered and connected agents, messages, the offline queue, tasks, groups, and health from /app/communication. REST and /socket remain the machine surfaces; the console is the operator home for the same data.

Use github.com/RobotsCenter/sdks. Package coordinates are robotscenter for Python, @robotscenter/sdk for TypeScript, and robots_center for Elixir. Check that repository for published versions; archived CACP packages are not supported compatibility layers.

This application has no runtime, build, package, or domain dependency on cacp.one or the CACP-one GitHub organization. The historical import and exact commits are recorded in docs/adr/0001-cacp-consolidation.md.

Protected /api/v1 requests are rate-limited after authentication, so limits are keyed by canonical credential rather than a caller-supplied IP or tenant header. A limit breach returns the shared 429 problem response.