Skip to main content
POST
Send a message to an agent and receive a reply (sync / SSE).

Authorizations

Authorization
string
header
required

Pass a user JWT or a oag_ User API Key on the Authorization: Bearer <token> header. Both are validated by openapi-gateway against the Auth service.

Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.

Removed in v1.1.0: the legacy agents:* / tasks:* / files:* / instances:* scope set has been dropped together with the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Headers

Idempotency-Key
string

Browser tasks require this header or the idempotency_key body field. If both are present they must agree. Reuse identical input and key after ambiguous failures; never retry with a replacement key. Does not apply to continuing an existing browser task.

Required string length: 1 - 128
Pattern: ^[!-~]+$

Path Parameters

agentId
string
required
Maximum string length: 128

Body

application/json
message
string
required

The message to send to the agent.

context_id
string

Optional conversation context ID for multi-turn conversations.

timeout_ms
integer<int64>

Per-request timeout in milliseconds. Default 120000 (2 minutes). Hard-capped at 115000 server-side so the response always has time to flush before the HTTP WriteTimeout (120s) fires. Values above 115000 are silently clamped; if the agent does not reply within the effective window the server returns service_timeout (HTTP 504) — see docs/reference/errors.md.

Required range: 0 <= x <= 115000
idempotency_key
string

Optional caller-generated idempotency key forwarded to Message Service as the chat_message's idempotency_key. Retries that race the same key dedup at MS (UNIQUE index on channel_messages). When omitted, the gateway generates a fresh UUID. The same key also doubles as the message_id an agent must echo back as in_reply_to on its reply.

metadata
object

Opaque caller-controlled key/value pairs merged into the channel metadata (e.g. trace_id, user_id, business tags). Reserved routing keys (protocol, caller_owner_id, target_agent_id, delivery_principal) are silently scrubbed server-side and cannot be overridden by the caller.

attachments
object[]

Optional list of files previously uploaded via POST /api/v1/files/presign-upload. Each file_id is resolved server-side to a presigned download URL and embedded in the chat_message envelope so the receiving agent can fetch the bytes without further BeeOS auth.

Maximum array length: 16

Response

Blocking: JSON envelope with agent reply. Streaming (Accept: text/event-stream): SSE stream — see InvokeEventStream for the per-frame schema (delta, error, done types).

success
boolean
required
data
object
required