openapi: 3.0.0
info:
description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
title: ArchAstro Platform Activity Feed Agents API
version: v1
tags:
- name: Agents
paths:
/api/v1/agents:
get:
description: 'Returns a paginated list of agents visible to the authenticated caller. Results are
ordered by creation time descending.
Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id`
to scope the list to a specific owner. Use `template_config` to find agents whose
last applied template matches a given config ID.
Pagination is page-based: pass `page` and `page_size` to navigate through large
result sets. When called under a developer app scope, only agents belonging to that
app are returned.'
operationId: get_api_v1_agents
parameters:
- description: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches.
example: string
in: query
name: template_config
required: false
schema:
type: string
- description: Free-text search string matched against the agent name, org, team, and owner fields.
example: string
in: query
name: search
required: false
schema:
type: string
- description: Number of agents to return per page. Defaults to `25`.
example: 1
in: query
name: page_size
required: false
schema:
type: integer
- description: Organization ID (`org_...`) to filter by. Returns only agents owned by this org.
example: string
in: query
name: org_id
required: false
schema:
type: string
- description: Page number to retrieve, 1-indexed. Defaults to `1`.
example: 1
in: query
name: page
required: false
schema:
type: integer
- description: User ID (`usr_...`) to filter by. Returns only agents owned by this user.
example: string
in: query
name: user
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AgentListResponse'
description: Successful response
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
summary: List agents
x-auth:
- bearer
- publishable_key
tags:
- Agents
post:
description: '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.'
operationId: post_api_v1_agents
parameters: []
requestBody:
content:
application/json:
schema:
example:
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
properties:
acl:
description: Access control list controlling which users, teams, or orgs can read or manage this agent.
example:
add:
- actions:
- read
- write
principal: string
principal_type: user
grants:
- actions:
- read
- write
principal: string
principal_type: user
remove:
- principal: string
principal_type: user
properties:
add:
description: 'Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
grants:
description: '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`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
remove:
description: 'Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.'
example:
- principal: string
principal_type: user
items:
description: Identifies a principal to be removed from an access-control list.
example:
principal: string
principal_type: user
properties:
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- principal_type
type: object
type: array
type: object
email:
description: Email address assigned to the agent. Used as the agent's contact identity.
example: user@example.com
type: string
identity:
description: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
example: string
type: string
lookup_key:
description: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
example: string
type: string
metadata:
description: Arbitrary key-value map stored on the agent. Not interpreted by the platform.
example:
key: value
type: object
model:
description: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model.
example: string
type: string
name:
description: Display name for the agent. Required when neither `template` nor `template_bundle` is provided.
example: Example Name
type: string
org:
description: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`.
example: string
type: string
originator:
description: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
example: string
type: string
phone_number:
description: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`.
example: '+15555550123'
type: string
profile_picture:
description: Profile picture to attach to the agent. All three subfields are required when this object is present.
example:
data: string
filename: string
mime_type: application/json
properties:
data:
description: Base64-encoded binary content of the image.
example: string
type: string
filename:
description: Original filename of the image, e.g. `avatar.png`.
example: string
type: string
mime_type:
description: MIME type of the image, e.g. `image/png` or `image/jpeg`.
example: application/json
type: string
required:
- data
- filename
- mime_type
type: object
team:
description: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`.
example: string
type: string
template:
description: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`.
example: string
type: string
template_bundle:
description: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`.
example:
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
properties:
configs:
description: Additional configuration resources (scripts, model configs, routine templates) referenced by `config_ref` entries in the template.
example:
- content: string
content_type: application/json
relative_path: tools/my-tool.yaml
items:
description: A supporting configuration resource included in a template bundle, such as a script, model config, or routine template referenced by the agent template.
example:
content: string
content_type: application/json
relative_path: tools/my-tool.yaml
properties:
content:
description: Full text content of the configuration file.
example: string
type: string
content_type:
description: MIME type of the configuration content, e.g. `"application/x-yaml"` or `"application/json"`. `null` if not specified.
example: application/json
type: string
relative_path:
description: Bundle-relative path to this config file. The path determines the config kind and its storage identity within the installation.
example: tools/my-tool.yaml
type: string
required:
- content
- relative_path
type: object
type: array
lookup_key_suffix:
description: 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.
example: string
type: string
setup_actions:
description: 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.
example:
- 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
items:
description: A post-install setup checklist item that the user must complete before the installed agent is fully operational.
example:
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
properties:
depends_on:
description: List of other setup action identifiers that must be completed before this action becomes actionable.
example:
- string
items:
type: string
type: array
description:
description: Markdown-formatted instructions or context shown beneath the checklist item. `null` if not provided.
example: An example description.
type: string
kind:
description: Category of setup step. One of `"env_var"` (configure an environment variable), `"install"` (complete an installation step), or `"custom"` (a user-defined action).
example: env_var
type: string
params:
description: 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`.
example:
key: value
type: object
required:
description: When `true`, this action must be completed before the checklist progress bar reaches 100%. Defaults to `true`.
example: true
type: boolean
sort_order:
description: Numeric sort position controlling the display order of this action in the checklist. Defaults to `0` when not specified.
example: 1
type: integer
title:
description: Short human-readable label displayed in the setup checklist.
example: Example Title
type: string
verify_config:
description: '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.'
example:
key: value
type: object
required:
- kind
- title
type: object
type: array
skills:
description: Skill bundles referenced by the template. Each entry includes the skill root and any supporting files.
example:
- 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
items:
description: A skill to install as part of a template bundle, consisting of a root `SKILL.md` definition and any accompanying support files.
example:
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
properties:
content:
description: Full text content of the `SKILL.md` file.
example: string
type: string
content_type:
description: MIME type of the `SKILL.md` content. Defaults to `text/markdown` when omitted.
example: application/json
type: string
files:
description: Additional files nested inside the skill folder, each with its own path and content.
example:
- content: string
content_type: application/json
relative_path: skills/my-skill/helpers.md
items:
description: A single file nested inside a skill folder, included as part of an install bundle.
example:
content: string
content_type: application/json
relative_path: skills/my-skill/helpers.md
properties:
content:
description: Full text content of the file.
example: string
type: string
content_type:
description: MIME type of the file content. Defaults to a value inferred from the file extension when omitted.
example: application/json
type: string
relative_path:
description: Path of this file relative to the skill folder root, e.g. `"skills/my-skill/helpers.md"`.
example: skills/my-skill/helpers.md
type: string
required:
- content
- relative_path
type: object
type: array
relative_path:
description: Bundle-relative path to the skill root, which must end in `/SKILL.md` (e.g. `"skills/my-skill/SKILL.md"`).
example: skills/my-skill/SKILL.md
type: string
required:
- content
- relative_path
type: object
type: array
template:
description: The agent template definition to install, including its path and raw content.
example:
content: string
content_type: application/json
relative_path: agent.yaml
properties:
content:
description: Full text content of the agent template file, typically a YAML document.
example: string
type: string
content_type:
description: MIME type of the template content. Defaults to `application/x-yaml` when omitted.
example: application/json
type: string
relative_path:
description: Bundle-relative path to the template file, used to derive its storage identity (e.g. `"agent.yaml"`).
example: agent.yaml
type: string
required:
- content
- relative_path
type: object
required:
- template
type: object
user:
description: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`.
example: string
type: string
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateResponse'
description: Successful response
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden — app scope required
'404':
description: Template not found
'409':
description: Conflict
'422':
description: Validation failed
summary: Create an agent
x-auth:
- bearer
- publishable_key
tags:
- Agents
/api/v1/agents/{agent}:
delete:
description: 'Permanently deletes an agent and all of its associated resources. This action cannot
be undone.
The authenticated caller must own the agent or hold sufficient permissions within its
owning org or team. When called under a developer app scope, the caller must hold the
app scope for the target app.'
operationId: delete_api_v1_agents__agent
parameters:
- description: ID (`agi_...`) or `lookup_key` of the agent to delete.
example: string
in: path
name: agent
required: true
schema:
type: string
responses:
'204':
description: No content
'401':
description: Unauthorized
'403':
description: App-scoped token required. Use a token scoped to the target app.; Permission denied. The connected account may not have the required permissions. Try reconnecting your account.
'404':
description: Agent not found
summary: Delete an agent
x-auth:
- bearer
- publishable_key
tags:
- Agents
get:
description: 'Returns the agent identified by ID or `lookup_key`. The authenticated caller must
own the agent or hold sufficient permissions within its owning org or team.
When called under a developer app scope, the agent must belong to that app. Use the
list endpoint to retrieve many agents at once.'
operationId: get_api_v1_agents__agent
parameters:
- description: ID (`agi_...`) or `lookup_key` of the agent to retrieve.
example: string
in: path
name: agent
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
description: Successful response
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
'404':
description: Agent not found
summary: Retrieve an agent
x-auth:
- bearer
- publishable_key
tags:
- Agents
patch:
description: 'Updates one or more fields on an existing agent. Only the fields you supply are
changed; omitted fields retain their current values.
To clear the agent''s default model, pass `model` as an empty string. The
authenticated caller must own the agent or hold write permissions within its owning
org or team. When called under a developer app scope, the caller must hold the app
# --- truncated at 32 KB (1263 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-agents-api-openapi.yml