# BeeOS ## Docs - [Agent Cards](https://docs.beeos.ai/a2a/agent-cards.md): Discover agent capabilities through the A2A Agent Card specification. - [JSON-RPC Methods](https://docs.beeos.ai/a2a/json-rpc.md): Complete reference for A2A v1.0 JSON-RPC methods. - [A2A Gateway](https://docs.beeos.ai/a2a/overview.md): Agent-to-Agent JSON-RPC protocol entry at a2a.beeos.ai — agent cards, tasks, streaming, and optional REST invoke. - [REST Invoke](https://docs.beeos.ai/a2a/rest-invoke.md): Simplified REST alternative to the full A2A JSON-RPC protocol. - [Streaming](https://docs.beeos.ai/a2a/streaming.md): Real-time A2A task updates via Server-Sent Events (SSE). - [Get agent details by ID.](https://docs.beeos.ai/api-reference/agents/get-agent-details-by-id.md) - [List agents owned by the caller.](https://docs.beeos.ai/api-reference/agents/list-agents-owned-by-the-caller.md) - [Send a message to an agent and receive a reply (sync / SSE).](https://docs.beeos.ai/api-reference/agents/send-a-message-to-an-agent-and-receive-a-reply-sync-sse.md): Sends a `chat_message` to the specified agent via Message Service channel-primitives and blocks until the agent replies (or times out). - [Update mutable agent fields (visibility / mcp_enabled).](https://docs.beeos.ai/api-reference/agents/update-mutable-agent-fields-visibility-mcp_enabled.md): Patch a narrow set of caller-managed agent properties. The whitelist is intentionally minimal — `description`, `name`, `version`, `avatar_url`, `capabilities`, and `skills` are reconciled from the pod-side `POST /api/v1/agents/sync` and would silently revert on the next sync if patched here. - [Close a conversation.](https://docs.beeos.ai/api-reference/conversations/close-a-conversation.md): Closes the underlying MS channel. After close, no further messages can be posted but historical messages remain readable via `GET /messages`. - [Get a single conversation's metadata.](https://docs.beeos.ai/api-reference/conversations/get-a-single-conversations-metadata.md) - [List conversations for the calling user against this agent.](https://docs.beeos.ai/api-reference/conversations/list-conversations-for-the-calling-user-against-this-agent.md): Returns long-lived dialog channels explicitly created via `POST /agents/{agentId}/conversations`. **Synchronous one-shot `POST /agents/{agentId}/invoke` calls do NOT appear here** — they create short-lived `protocol=openapi` task channels that surface under `GET /agents/{agentId}/tasks` and `GET /ta… - [List messages in a conversation (paged by offset).](https://docs.beeos.ai/api-reference/conversations/list-messages-in-a-conversation-paged-by-offset.md): Returns the durable conversation log. By default the response EXCLUDES ephemeral streaming chunks (`agent_reply_delta`, `agent_thought_chunk`, `agent_message_chunk`) — only finalized turns and tool messages are returned, so UIs render a clean transcript without pagination blowing up on token-level c… - [Open a new conversation.](https://docs.beeos.ai/api-reference/conversations/open-a-new-conversation.md): Creates a long-lived dialog channel. Does NOT carry an initial message — callers post the first `chat_message` via `POST /conversations/{convId}/messages` once the conversation exists. - [Post a new caller message into the conversation.](https://docs.beeos.ai/api-reference/conversations/post-a-new-caller-message-into-the-conversation.md): Non-blocking — returns 202 with the persisted `message_id`. The agent reply lands later via the SSE `/events` stream or a follow-up `GET /messages?since=`. Conversations have no per-turn timeout; use `tasks` when you need a bounded reply window. - [SSE stream of new messages on the conversation.](https://docs.beeos.ai/api-reference/conversations/sse-stream-of-new-messages-on-the-conversation.md): Same wire format as `tasks/{taskId}/events`. Unlike the task variant, the conversation event stream does NOT auto-close on agent reply — it stays open until the caller disconnects or the conversation is closed via `DELETE /conversations/{convId}`. - [List available providers (catalog)](https://docs.beeos.ai/api-reference/deploy/list-available-providers-catalog.md) - [List deploy models](https://docs.beeos.ai/api-reference/deploy/list-deploy-models.md) - [List deploy regions](https://docs.beeos.ai/api-reference/deploy/list-deploy-regions.md) - [Request a presigned upload URL.](https://docs.beeos.ai/api-reference/files/request-a-presigned-upload-url.md): Returns a single-use presigned PUT URL the client uses to upload directly to BeeOS-managed object storage (S3 / MinIO in production, local disk in dev). The returned `file_id` is stable and can be attached to subsequent `POST /agents/{agentId}/invoke` / `POST /agents/{agentId}/tasks` bodies via the… - [Resolve a file_id to metadata + presigned download URL.](https://docs.beeos.ai/api-reference/files/resolve-a-file_id-to-metadata-+-presigned-download-url.md): Returns the filename / content-type / size of a previously uploaded file along with a presigned GET URL (TTL set by the storage backend, typically 24h on S3). Agents receive the same URL when the file is attached to an invoke / task envelope; this endpoint exists so callers can fetch their own uploa… - [Deploy a new instance (catalog-driven via `variantId` or explicit).](https://docs.beeos.ai/api-reference/instances/deploy-a-new-instance-catalog-driven-via-`variantid`-or-explicit.md) - [Destroy (terminate) an instance](https://docs.beeos.ai/api-reference/instances/destroy-terminate-an-instance.md) - [Get an instance by id](https://docs.beeos.ai/api-reference/instances/get-an-instance-by-id.md) - [List the caller's instances](https://docs.beeos.ai/api-reference/instances/list-the-callers-instances.md) - [Restart an instance](https://docs.beeos.ai/api-reference/instances/restart-an-instance.md) - [Start an instance](https://docs.beeos.ai/api-reference/instances/start-an-instance.md) - [Stop an instance](https://docs.beeos.ai/api-reference/instances/stop-an-instance.md) - [Cancel an in-flight task.](https://docs.beeos.ai/api-reference/tasks/cancel-an-in-flight-task.md): Emits a `chat_cancel` envelope so the agent can abort its in-flight turn cleanly, then closes the channel with `reason=canceled`. Idempotent — re-issuing cancel on an already-canceled task is a no-op and still returns the snapshot. - [Get a task's current state snapshot.](https://docs.beeos.ai/api-reference/tasks/get-a-tasks-current-state-snapshot.md): Returns the snapshot derived by `msgderive` from the task's channel-message log — safe to call at any cadence; the resolver is a pure function and terminal states short-circuit polling loops. - [List all of the caller's tasks across every agent.](https://docs.beeos.ai/api-reference/tasks/list-all-of-the-callers-tasks-across-every-agent.md): Cross-agent task list (P2-B). Returns every task channel the caller owns, newest first — the unified "my tasks" view for SDKs that need to render a multi-agent inbox without fanning out per-agent. - [List registered webhooks for a task.](https://docs.beeos.ai/api-reference/tasks/list-registered-webhooks-for-a-task.md) - [List the caller's tasks for this agent.](https://docs.beeos.ai/api-reference/tasks/list-the-callers-tasks-for-this-agent.md): Returns the caller's tasks against this agent, filtered server-side by participation (the caller's `user:`) and client-side by `target_agent_id == {agentId}` AND `protocol == "openapi"` so the endpoint stays scoped to OpenAPI-created tasks (excludes conversations and other-protocol channels). - [List the persisted message log for a task (paged by offset).](https://docs.beeos.ai/api-reference/tasks/list-the-persisted-message-log-for-a-task-paged-by-offset.md): Returns the channel-message log for a task — `chat_message`, `agent_reply`, `chat_cancel`, `user.continue`, etc. By default EXCLUDES ephemeral streaming chunks (`agent_reply_delta`, `agent_thought_chunk`, `agent_message_chunk`); set `include_deltas=true` to receive them. `latest_offset` always refle… - [List webhook delivery attempts (audit log).](https://docs.beeos.ai/api-reference/tasks/list-webhook-delivery-attempts-audit-log.md): Returns the most recent per-attempt rows for this webhook subscription, newest first. P2-A — durable delivery audit log + retry queue. - [Manually replay a webhook delivery.](https://docs.beeos.ai/api-reference/tasks/manually-replay-a-webhook-delivery.md): Clones a terminal-failure or dead-lettered delivery row into a fresh `pending` row that the background dispatcher will pick up on its next poll. The original row is preserved for audit. The returned `WebhookDeliveryResponse` is the new pending row — poll the delivery list or watch the callback URL i… - [Register a webhook callback for terminal task events.](https://docs.beeos.ai/api-reference/tasks/register-a-webhook-callback-for-terminal-task-events.md): Subscribes a caller-supplied HTTPS endpoint to receive POST callbacks when the task reaches a terminal state (`succeeded` / `failed` / `canceled` / `timeout` / `rejected`). Idempotent on `(task_id, url)` — re-registering the same URL updates the token. - [Resume a task from input_required / auth_required.](https://docs.beeos.ai/api-reference/tasks/resume-a-task-from-input_required-auth_required.md): Publishes a `user.continue` (or `user.auth_grant` when `auth_grant=true`) envelope so the agent can resume from a paused `input_required` / `auth_required` state. Returns the snapshot AFTER the envelope is published — typically `running`, or still `input_required` if the agent hasn't processed the r… - [Submit an async task to an agent.](https://docs.beeos.ai/api-reference/tasks/submit-an-async-task-to-an-agent.md): Creates a single-shot task channel and publishes the initial `chat_message` envelope, then returns 202 with the task_id. The agent reply lands asynchronously — callers either poll `GET /tasks/{taskId}` or subscribe to the SSE event stream at `GET /tasks/{taskId}/events`. - [Subscribe to a task's event stream (SSE).](https://docs.beeos.ai/api-reference/tasks/subscribe-to-a-tasks-event-stream-sse.md): SSE proxy onto the underlying MS conversation. Each event is `message` (JSON payload mirroring the on-channel envelope: `type`, `message_id`, `offset`, `in_reply_to`, `publisher_id`, `payload`, `created_at`). - [Unsubscribe a webhook.](https://docs.beeos.ai/api-reference/tasks/unsubscribe-a-webhook.md) - [Public Architecture Overview](https://docs.beeos.ai/architecture/public-overview.md): The four public BeeOS hosts (openapi, a2a, mcp, agent) and how requests flow through each into the control plane. - [Authentication & API Keys](https://docs.beeos.ai/authentication.md): Credentials accepted by every BeeOS public surface — User JWT, oag_ User API Keys, bak_ Agent API Keys, and OAuth 2.1. - [Agent Author Quickstart](https://docs.beeos.ai/guides/agent-author-quickstart.md): Five rules every agent must follow to reply correctly through the BeeOS message bus. - [Calling Agents](https://docs.beeos.ai/guides/calling-agents.md): Three invocation modes — synchronous blocking, streaming SSE, and asynchronous tasks — across OpenAPI, A2A, and MCP. - [Choosing a Protocol](https://docs.beeos.ai/guides/choosing-a-protocol.md): Decide between OpenAPI (platform REST), A2A (agent-to-agent), and MCP (model-context tools) for a given integration. - [Conversations](https://docs.beeos.ai/guides/conversations.md): Long-lived multi-turn dialogs with the agent. Compare against tasks (single-shot) and pick the right primitive. - [Streaming](https://docs.beeos.ai/guides/streaming.md): SSE streaming across all three protocol surfaces — connection rules, reconnect with since cursor, and frame shapes. - [Webhooks](https://docs.beeos.ai/guides/webhooks.md): Receive terminal-state task notifications with HMAC-signed payloads, exponential-backoff retry, and audit log. - [Introduction](https://docs.beeos.ai/introduction.md): Build, deploy, and connect AI agents on BeeOS — one platform, four public protocol surfaces. - [OAuth 2.1 Flow](https://docs.beeos.ai/mcp/oauth.md): OAuth 2.1 + PKCE authentication for MCP clients. - [MCP Gateway](https://docs.beeos.ai/mcp/overview.md): Model Context Protocol entry at mcp.beeos.ai — tools/list, tools/call, OAuth 2.1 + PKCE for spec-compliant clients. - [Resources](https://docs.beeos.ai/mcp/resources.md): Read-only data resources and prompt templates exposed by MCP agents. - [Tools](https://docs.beeos.ai/mcp/tools.md): Discover and invoke agent tools via the MCP protocol — including attachments, idempotency keys, and streaming. - [Quickstart](https://docs.beeos.ai/quickstart.md): Deploy your first agent and invoke it in 5 minutes — typed SDK, curl, and Go. - [Error Reference](https://docs.beeos.ai/reference/errors.md): Every error.code returned by the BeeOS public surfaces, the HTTP status that wraps it, and the recovery hint. - [SDK Changelog](https://docs.beeos.ai/sdks/changelog.md): Versioned changes to the OpenAPI contract and the generated @beeos-ai/sdk and github.com/beeos-ai/sdk-go SDKs. - [Go SDK](https://docs.beeos.ai/sdks/go.md): Install and use github.com/beeos-ai/sdk-go — the auto-generated Go client for the BeeOS OpenAPI. - [SDK Migration](https://docs.beeos.ai/sdks/migration.md): Upgrade paths between @beeos-ai/sdk versions (0.3.x → 0.4.x and beyond), plus hand-rolled HTTP migration recipes. - [TypeScript SDK](https://docs.beeos.ai/sdks/typescript.md): Install and use @beeos-ai/sdk — the auto-generated TypeScript client for the BeeOS OpenAPI. ## OpenAPI Specs - [beeos-platform-v1](https://docs.beeos.ai/openapi/beeos-platform-v1.yaml) - [beeos-platform-v1-zh](https://docs.beeos.ai/openapi/beeos-platform-v1-zh.yaml) - [beeos-agent-integration-v1](https://docs.beeos.ai/openapi/beeos-agent-integration-v1.yaml) - [openapi](https://docs.beeos.ai/api-reference/openapi.json)