Skip to main content
POST
/
api
/
v1
/
agents
/
{agentId}
/
tasks
Submit an async task to an agent.
curl --request POST \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "context_id": "<string>",
  "deadline_ms": 302400000,
  "idempotency_key": "<string>",
  "metadata": {},
  "attachments": [
    {
      "file_id": "<string>",
      "filename": "<string>",
      "content_type": "<string>"
    }
  ]
}
'
{
  "success": true,
  "data": {
    "task_id": "ch-task-uuid",
    "agent_id": "agent-uuid",
    "status": "queued",
    "created_at": "2026-05-14T18:00:00Z"
  }
}

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.

Path Parameters

​
agentId
string
required
Maximum string length: 128

Body

application/json
​
message
string
required

Initial user prompt. Wrapped into a chat_message envelope.

​
context_id
string

Optional existing conversation/channel ID to reuse instead of creating a fresh task channel. Rare; most callers omit this.

​
deadline_ms
integer<int64>

Task deadline in milliseconds. When > 0, the channel auto-closes with status=timeout if no terminal reply lands in this window. Max 7 days (server-side cap).

Required range: 0 <= x <= 604800000
​
idempotency_key
string

Forwarded to MS's channel_messages UNIQUE index. Re-submitting with the same key returns the original task_id rather than spawning a duplicate. Recommended for retry-prone callers.

​
metadata
object

Caller-supplied correlation tags (trace_id, business labels). Reserved chatinvoke routing keys (protocol, caller_owner_id, target_agent_id, delivery_principal) are overwritten by the gateway and stripped from the response.

​
attachments
object[]

Optional list of files previously uploaded via POST /api/v1/files/presign-upload. Resolved server-side and embedded in the initial chat_message envelope.

Maximum array length: 16

Response

Task accepted. Reply will land asynchronously.

​
success
boolean
required
​
data
object
required