Agents

Create agent

Create a saved, versioned Agent (version 1). The request is strict JSON (1 MiB maximum; unknown fields are rejected). Idempotency-Key is optional; the service generates one when omitted, so send your own key when you retry.

post/v1/agents

Request

  • Base URL: https://api.sandbase.ai
  • URL: https://api.sandbase.ai/v1/agents
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Headers

Idempotency-Keystring

Optional. Send a stable key so retries do not create duplicates.

OpenAI-Beta'agents=v1'

Optional OpenAI SDK header. When present it must be agents=v1.

Request body

namestring
modelstring required

Model ID from the Models API, such as deepseek/deepseek-v4-flash.

instructionsstring
descriptionstring
metadataobject

Keys up to 64 characters.

service_tier'auto' | 'default' | 'flex' | 'priority' | 'fast'
runtime_profile'codex' | 'claude' | 'mcode'
notestring

Optional change note recorded on version 1.

multi_agentunknown

Response

Agent created

idstring required

Agent ID (agt_ prefix).

object'agent' required
modelstring required
namestring nullable required
instructionsstring nullable required
toolsobject[] required
reasoningobject required
service_tierstring required
multi_agentobject required

Always reports enabled false.

visibility'private' | 'public' required
status'active' | 'archived' required
versioninteger required

Current version number.

row_versioninteger required

Compare-and-set token for PATCH, archive, unarchive, and restore.

projection_statusstring required

Whether the current version is ready for execution. Sessions require ready.

runtime_profile'codex' | 'claude' | 'mcode' required
descriptionstring required
metadataobject required
created_atinteger required

Unix seconds.

updated_atinteger required

Unix seconds.

archived_atinteger nullable required

Unix seconds.

failure_codestring

Changes

No recorded changes to this operation across all 1 revision of this API.