---
title: "Create an agent"
method: POST
path: "/api/v1/agents"
---

# Create an agent

`POST /api/v1/agents`

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.

## Request body

- object
  - `acl` object — Access control list controlling which users, teams, or orgs can read or manage this agent.
    - `add` object[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `grants` object[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `remove` object[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
      - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
  - `email` string — Email address assigned to the agent. Used as the agent's contact identity.
  - `identity` string — System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
  - `lookup_key` string — Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
  - `metadata` object — Arbitrary key-value map stored on the agent. Not interpreted by the platform.
  - `model` string — Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model.
  - `name` string — Display name for the agent. Required when neither `template` nor `template_bundle` is provided.
  - `org` string — Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`.
  - `originator` string — Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
  - `phone_number` string — Phone number assigned to the agent in E.164 format, e.g. `+15550001234`.
  - `profile_picture` object — Profile picture to attach to the agent. All three subfields are required when this object is present.
    - `data` string, required — Base64-encoded binary content of the image.
    - `filename` string, required — Original filename of the image, e.g. `avatar.png`.
    - `mime_type` string, required — MIME type of the image, e.g. `image/png` or `image/jpeg`.
  - `team` string — Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`.
  - `template` string — ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`.
  - `template_bundle` object — Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`.
    - `configs` object[] — Additional configuration resources (scripts, model configs, routine templates) referenced by `config_ref` entries in the template.
      - `content` string, required — Full text content of the configuration file.
      - `content_type` string — MIME type of the configuration content, e.g. `"application/x-yaml"` or `"application/json"`. `null` if not specified.
      - `relative_path` string, required — Bundle-relative path to this config file. The path determines the config kind and its storage identity within the installation.
    - `lookup_key_suffix` string — A string appended to the lookup key of every uploaded config and rewritten into every `config_ref` in the template body. Should be stable for a given install and unique across installs to avoid key collisions.
    - `setup_actions` object[] — Post-install checklist items created alongside the agent. Each action is inserted as a pending setup step that the user must complete before the agent is fully operational.
      - `depends_on` string[] — List of other setup action identifiers that must be completed before this action becomes actionable.
      - `description` string — Markdown-formatted instructions or context shown beneath the checklist item. `null` if not provided.
      - `kind` string, required — Category of setup step. One of `"env_var"` (configure an environment variable), `"install"` (complete an installation step), or `"custom"` (a user-defined action).
      - `params` object — Kind-specific configuration for the action. For `"env_var"` steps this typically includes `key` and `scope`; for `"install"` steps it includes `installation_kind`. Shape varies by `kind`.
      - `required` boolean — When `true`, this action must be completed before the checklist progress bar reaches 100%. Defaults to `true`.
      - `sort_order` integer — Numeric sort position controlling the display order of this action in the checklist. Defaults to `0` when not specified.
      - `title` string, required — Short human-readable label displayed in the setup checklist.
      - `verify_config` object — Configuration passed to the runtime verifier to determine whether the action has been completed, e.g. `{"type": "secret_present"}`. `null` if no automated verification is configured.
    - `skills` object[] — Skill bundles referenced by the template. Each entry includes the skill root and any supporting files.
      - `content` string, required — Full text content of the `SKILL.md` file.
      - `content_type` string — MIME type of the `SKILL.md` content. Defaults to `text/markdown` when omitted.
      - `files` object[] — Additional files nested inside the skill folder, each with its own path and content.
        - `content` string, required — Full text content of the file.
        - `content_type` string — MIME type of the file content. Defaults to a value inferred from the file extension when omitted.
        - `relative_path` string, required — Path of this file relative to the skill folder root, e.g. `"skills/my-skill/helpers.md"`.
      - `relative_path` string, required — Bundle-relative path to the skill root, which must end in `/SKILL.md` (e.g. `"skills/my-skill/SKILL.md"`).
    - `template` object, required — The agent template definition to install, including its path and raw content.
      - `content` string, required — Full text content of the agent template file, typically a YAML document.
      - `content_type` string — MIME type of the template content. Defaults to `application/x-yaml` when omitted.
      - `relative_path` string, required — Bundle-relative path to the template file, used to derive its storage identity (e.g. `"agent.yaml"`).
  - `user` string — User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`.

## Response `200`

Successful response

- AgentCreateResponse — The response returned by `POST /api/v1/agents`. Contains all agent fields plus an optional `installed_configs` array when a `template_bundle` was supplied in the request.
  - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
    - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
      - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
  - `app` string — ID of the app this agent belongs to (`dap_...`).
  - `created_at` string, date-time — When the agent was created (ISO 8601).
  - `default_model` string — Default AI model the agent uses when no model is specified at runtime, e.g. `"claude-3-5-sonnet-20241022"`. `null` if not configured.
  - `email` string — Email address assigned to this agent for inbound email handling. `null` if not configured.
  - `id` string, required — Agent ID (`agi_...`).
  - `identity` string — System prompt or persona description that shapes the agent's behavior. `null` if not set.
  - `installed_configs` InstalledConfigEntry[] — List of config records created as part of this request's `template_bundle` install. One entry per persisted config, sorted by `key`. Omitted entirely when the request did not include a `template_bundle`.
    - `id` string, required — ID of the persisted config record (`cfg_...`).
    - `key` string, required — Caller-supplied correlation key echoed back from the request. For top-level configs this is the original `lookup_key` (before any suffix is applied). For skill file children it is the composite `"<skill_lookup_key>:<relative_path>"` string, since file rows have no lookup_key of their own.
    - `kind` string, required — Type of config that was created. One of `"Skill"`, `"File"`, `"Script"`, `"AgentTemplate"`, or `"Config"`.
    - `lookup_key` string — Stored `lookup_key` for this config after any suffix has been applied. `null` for `File` children inside a skill bundle, which are keyed by `(parent_id, relative_path)` rather than by `lookup_key`.
  - `lookup_key` string — Unique, stable identifier for the agent within its app. `null` if not set.
  - `metadata` object — Arbitrary key-value metadata attached to the agent. `null` if none was provided.
  - `name` string — Human-readable display name for the agent. `null` if not set.
  - `org` string — ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org.
  - `originator` string — Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set.
  - `phone_number` string — Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured.
  - `sandbox` string — ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox.
  - `team` string — ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.
  - `updated_at` string, date-time — When the agent record was last modified (ISO 8601).
  - `user` string — ID of the user that owns this agent (`usr_...`). `null` if owned by a team.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden — app scope required
- `404` — Template not found
- `409` — Conflict
- `422` — Validation failed

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)