v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create an agent

Creates a new agent. Supports two mutually exclusive provisioning modes.

Template mode — pass template with the ID or lookup_key of an existing AgentTemplate config. The agent's tools, routines, skills, and installations are provisioned from that template's config_ref entries.

Bundle mode — pass template_bundle with a self-contained install payload (AgentTemplate body plus every skill, script, and config it references). The entire bundle commits in a single transaction; any failure rolls back the whole install and the response includes installed_configs[] — one entry per persisted config.

Pass exactly one of template or template_bundle. If neither is supplied, name is required and a blank agent is created. Requires authentication; when called under a developer app scope (/developer/apps/:app/...), the caller must hold the app scope for the target app.

post/api/v1/agents

Request body

emailstring

Email address assigned to the agent. Used as the agent's contact identity.

identitystring

System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.

lookup_keystring

Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.

metadataobject

Arbitrary key-value map stored on the agent. Not interpreted by the platform.

modelstring

Default AI model identifier for this agent, e.g. claude-sonnet-4-5. Overridden per-request when the caller specifies a model.

namestring

Display name for the agent. Required when neither template nor template_bundle is provided.

orgstring

Organization ID (org_...) that should own this agent. Mutually exclusive with team and user.

originatorstring

Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.

phone_numberstring

Phone number assigned to the agent in E.164 format, e.g. +15550001234.

teamstring

Team ID (team_...) that should own this agent. Mutually exclusive with org and user.

templatestring

ID (cfg_...) or lookup_key of an existing AgentTemplate config to provision from. Mutually exclusive with template_bundle.

userstring

User ID (usr_...) that should own this agent. Mutually exclusive with org and team.

Example request

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "email": "user@example.com",
  "identity": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "model": "string",
  "name": "Example Name",
  "org": "string",
  "originator": "string",
  "phone_number": "+15555550123",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "team": "string",
  "template": "string",
  "template_bundle": {
    "configs": [
      {
        "content": "string",
        "content_type": "application/json",
        "relative_path": "tools/my-tool.yaml"
      }
    ],
    "lookup_key_suffix": "string",
    "setup_actions": [
      {
        "depends_on": [
          "string"
        ],
        "description": "An example description.",
        "kind": "env_var",
        "params": {
          "key": "value"
        },
        "required": true,
        "sort_order": 1,
        "title": "Example Title",
        "verify_config": {
          "key": "value"
        }
      }
    ],
    "skills": [
      {
        "content": "string",
        "content_type": "application/json",
        "files": [
          {
            "content": "string",
            "content_type": "application/json",
            "relative_path": "skills/my-skill/helpers.md"
          }
        ],
        "relative_path": "skills/my-skill/SKILL.md"
      }
    ],
    "template": {
      "content": "string",
      "content_type": "application/json",
      "relative_path": "agent.yaml"
    }
  },
  "user": "string"
}

Response

Successful response

appstring

ID of the app this agent belongs to (dap_...).

created_atstring date-time

When the agent was created (ISO 8601).

default_modelstring

Default AI model the agent uses when no model is specified at runtime, e.g. "claude-3-5-sonnet-20241022". null if not configured.

emailstring

Email address assigned to this agent for inbound email handling. null if not configured.

idstring required

Agent ID (agi_...).

identitystring

System prompt or persona description that shapes the agent's behavior. null if not set.

lookup_keystring

Unique, stable identifier for the agent within its app. null if not set.

metadataobject

Arbitrary key-value metadata attached to the agent. null if none was provided.

namestring

Human-readable display name for the agent. null if not set.

orgstring

ID of the organization this agent belongs to (org_...). null for agents outside an org.

originatorstring

Free-form label identifying the source or author of the agent, e.g. a username or service name. null if not set.

phone_numberstring

Phone number assigned to this agent for inbound SMS or voice handling. null if not configured.

sandboxstring

ID of the sandbox environment this agent is scoped to (sbx_...). null for agents not scoped to a sandbox.

teamstring

ID of the team that owns this agent (tea_...). null if owned by a user rather than a team.

updated_atstring date-time

When the agent record was last modified (ISO 8601).

userstring

ID of the user that owns this agent (usr_...). null if owned by a team.

Example response

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "default_model": "claude-3-5-sonnet-20241022",
  "email": "user@example.com",
  "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "identity": "You are a helpful assistant.",
  "installed_configs": [
    {
      "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "key": "my-skill",
      "kind": "Skill",
      "lookup_key": "my-skill"
    }
  ],
  "lookup_key": "my-agent",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "originator": "my-service",
  "phone_number": "+15555550123",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}