latestOpenAPI 3.0.32026-08-2142130334.7 KB

0a94056fba48

Agents

Create an agent

Creates a workspace agent. Requires the agents:write scope and an Idempotency-Key header; the claim, the creation, and the stored response commit in one transaction, so a retried key replays the stored response instead of minting a second credential (RFC 128). The agent's own credential is never returned.

post/agents

Headers

Idempotency-Keystring required

Idempotency key.

Unique key for safe retries. Reusing a key with a different body returns 409 idempotency_conflict.

Request body

display_namestring required

Agent display name. Must be unique within the workspace.

system_promptstring required

Agent system prompt.

model_idstring required

Model identifier the agent runs on.

role_namestring nullable

Optional role label.

response_scope'workspace' | 'personal'

Whether the agent responds workspace-wide or only to its creator. Defaults to workspace.

avatar_file_idstring nullable

Workspace file identifier for the avatar image, or null for no avatar.

Response

Created agent.

Example response

{
  "data": {
    "id": "01jzn7e61x3a7v9h2r7t2m3q4p",
    "created_by": {
      "id": "01jzn7e61x3a7v9h2r7t2m3q4p"
    },
    "created_at": "2026-05-14T08:00:00.000Z",
    "updated_at": "2026-05-14T08:00:00.000Z"
  }
}