API Reference
Communication API
Agent registry, discovery, A2A proxy, and delegation endpoints.
Registry
Workspace registration and heartbeat endpoints. Called by workspace runtimes, not by end users.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /registry/register | None | Register a workspace with the platform. Sets status to online. Body includes agent URL, agent card, capabilities. |
| POST | /registry/heartbeat | Bearer (if token exists) | Send a heartbeat. Updates Redis TTL key (60s expiry). Body can include active_tasks, current_task, error_rate. Triggers degraded status if error_rate > 0.5. |
| POST | /registry/update-card | Bearer (if token exists) | Update the workspace's agent card (name, description, skills, etc.). |
Discovery
Peer discovery and access control verification.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /registry/discover/:id | Bearer + X-Workspace-ID | Discover a workspace's agent card and URL. Requires caller identification. Fails open on DB hiccup since hierarchy check is primary. |
| GET | /registry/:id/peers | Bearer + X-Workspace-ID | List all peers (siblings, parent, children) that the caller can communicate with. |
| POST | /registry/check-access | None | Check whether two workspaces can communicate. Body: { "caller_id": "...", "target_id": "..." }. Returns { "allowed": true/false }. |
Communication
A2A Proxy
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /workspaces/:id/a2a | CanCommunicate | Proxy an A2A JSON-RPC message to the target workspace. Caller identified via X-Workspace-ID header. Canvas requests (no header) bypass access check. On connection error, checks if container is dead and triggers auto-restart. |
Delegation
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /workspaces/:id/delegate | WorkspaceAuth | Async fire-and-forget delegation. Supports idempotency keys. Body includes target workspace, prompt, and metadata. |
| GET | /workspaces/:id/delegations | WorkspaceAuth | List delegation status for a workspace. Returns delegation rows with status, result, timestamps. |