Skip to main content
POST
Create an agent

Authorizations

x-api-key
string
header
required

Workspace API key. Current accepted keys use the ando_sk_ prefix.

Headers

Idempotency-Key
string
required

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

Maximum string length: 255

Body

application/json

Agent creation request. Requires an Idempotency-Key header; a retried key replays the stored response instead of minting a second credential.

display_name
string
required

Agent display name. Must be unique within the workspace.

system_prompt
string
required

Agent system prompt.

model_id
string
required

Model identifier the agent runs on.

role_name
string | null

Optional role label.

response_scope
enum<string>

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

Available options:
workspace,
personal
avatar_file_id
string | null

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

Response

Created agent.

Agent response.

data
object
required

A workspace agent's lifecycle projection. The agent's own credential is never returned.