Create Agent

POST/v1/agents

Create a saved Agent at version 1. The body is strict JSON: unknown fields return 400. multi_agent must be omitted or null.

Headers

Optional<string>Idempotency-Key

Optional. When omitted the service generates one, so a retried request can create a duplicate. Send your own stable key for retries.

Request body

JSON object.

stringmodelrequired

Required model ID from the Models API, up to 200 characters. There is no default; omitting model returns 400. The examples use deepseek/deepseek-v4-flash.

Optional<string>name

Display name, up to 128 characters.

Optional<string>instructions

System instructions, up to 256 KiB.

Optional<string>runtime_profile

Execution runtime: codex (default), claude, or mcode.

Optional<array>skills

Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. Up to 32. On a new binding, null pins the current default when the Agent is saved. For an existing binding, null preserves its pinned version; supply an explicit version to upgrade.

Optional<array>mcp_connections

MCP references: {connection_id, server_label, allowed_tools, required}. Up to 32; server_label must be unique in the Agent.

Optional<array>tools

Up to 64 function tools plus at most one web_search tool. Sessions currently require web_search mode disabled, and client-side function results are not supported yet.

Optional<object>text

format.type text or json_schema (with an object schema); verbosity low, medium, or high.

Optional<object>reasoning

effort none, minimal, low, medium, high, xhigh, or max; summary concise, detailed, or auto.

Optional<string>service_tier

auto (default), default, flex, priority, or fast.

Optional<object>metadata

Up to 16 string pairs; keys up to 64 and values up to 512 characters.

Optional<string>description

Longer description, up to 4096 characters.

Optional<string>note

Change note recorded on version 1.

Agent object

Returned by create, get, update, archive, unarchive, restore, and clone.

stringidrequired

Agent ID with the agt_ prefix.

stringobjectrequired

Always agent.

integerversionrequired

Current version. Every effective write creates a new version.

integerrow_versionrequired

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

stringstatusrequired

active or archived.

stringprojection_statusrequired

Execution readiness of the current version. Sessions, Services, and Schedules need ready; a new Agent can briefly report pending.

stringruntime_profilerequired

codex, claude, or mcode.

stringvisibilityrequired

private for your Agents; public for catalog entries.

integer · nullcreated_at · updated_at · archived_atrequired

Unix seconds. archived_at is null while active.

curl -X POST https://api.sandbase.ai/v1/agents \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Idempotency-Key: create-research-agent-1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research assistant",
    "model": "deepseek/deepseek-v4-flash",
    "instructions": "Answer with cited sources.",
    "metadata": {
      "team": "research"
    }
  }'

Response201 Created

{
  "id": "agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60",
  "object": "agent",
  "name": "Research assistant",
  "model": "deepseek/deepseek-v4-flash",
  "instructions": "Answer with cited sources.",
  "tools": [],
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "service_tier": "auto",
  "multi_agent": {
    "enabled": false,
    "max_concurrent_subagents": null
  },
  "visibility": "private",
  "status": "active",
  "version": 1,
  "row_version": 1,
  "projection_status": "ready",
  "runtime_profile": "codex",
  "description": "",
  "metadata": {
    "team": "research"
  },
  "mcp_connections": [],
  "skills": [],
  "created_at": 1791273600,
  "updated_at": 1791273600,
  "archived_at": null
}