> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents API
> Manage agents, versions, publishing, and deployment over HTTP.
An **agent** is the conversational unit you publish to a channel. Its behavior lives in immutable **versions** — each version holds an `AgentConfig` (instructions, voice, tools, and more). You edit a draft version, publish it, then assign it to phone numbers or expose it as a SIP endpoint.
All endpoints live under the `/core` prefix. Pass your credential in the `Authorization` header on every request; a personal access token (`pat_`) also requires the `X-Anyreach-Org` header. See [Authentication](/api-reference/authentication). For the product concepts behind these endpoints, see [Agents](/agents/overview).
## Scopes
| Action | Required scope |
| --------------------------------------- | ---------------------------------- |
| Read agents and versions | `agents:read` (or `agents:manage`) |
| Create, update, delete, publish, deploy | `agents:manage` |
Read endpoints accept either `agents:read` or `agents:manage`. Every write, publish, and deploy endpoint requires `agents:manage`.
## Agents
| Method | Path | Scope | Description |
| -------- | ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/core/agents` | read | List agents. Filter by `name`, `active`, `is_demo`, `metadata` (JSON object string), and `created_*`/`updated_*` timestamps. Paginate with `limit` and `cursor`. |
| `POST` | `/core/agents` | manage | Create an agent. Body: `name` (required), `description`, `active` (default `true`), `is_demo` (default `false`), `metadata`. |
| `GET` | `/core/agents/{id}` | read | Get one agent, including its versions, assigned phone numbers, widgets, SIP endpoint state, and conversation statistics. |
| `PUT` | `/core/agents/{id}` | manage | Update an agent's `name`, `description`, `active`, `is_demo`, or `metadata`. |
| `DELETE` | `/core/agents/{id}` | manage | Delete an agent. Returns `204`. |
## Versions
A version's config is immutable once published — published versions reject updates. Create a new version (optionally from `base_version`) to make further changes.
| Method | Path | Scope | Description |
| ------ | ------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/core/agents/{id}/versions` | read | List an agent's versions. Filter by `version`, `published`, and `created_*`/`updated_*` timestamps. Paginate with `limit` and `cursor`. |
| `GET` | `/core/agents/{id}/versions/{version}` | read | Get one version. `version` is a number or the literal `latest`. Requesting `latest` ensures a draft exists. |
| `POST` | `/core/agents/{id}/versions` | manage | Create a version. Body: either `config` (an `AgentConfig`) or `base_version` (a version number to copy from) — exactly one is required. |
| `PUT` | `/core/agents/{id}/versions/{version}` | manage | Update an unpublished version's `config` or `instruction_builder_inputs`. Returns `400` if the version is published. |
| `POST` | `/core/agents/{id}/versions/compare` | read | Stream an LLM-generated summary of the diff between two versions. Body: `from_version`, `to_version`. Response is `text/plain`. |
| `POST` | `/core/agents/{id}/versions/{version}/generate-instructions` | manage | Start async instruction generation from the version's `instruction_builder_inputs`. Returns `202`. Requires `instruction_builder_inputs` to be set; rejects published versions. |
| `POST` | `/core/agents/{id}/versions/{version}/publish` | manage | Publish the version and assign or unassign phone numbers. See below. |
### Publish a version
`POST /core/agents/{id}/versions/{version}/publish` marks the version published and, optionally, deploys it to phone numbers. The response is the list of affected phone numbers.
| Field | Type | Default | Description |
| ------------------------ | ---------- | --------- | -------------------------------------------------- |
| `phone_numbers` | `string[]` | `null` | Phone numbers to assign this version to. |
| `unassign_phone_numbers` | `string[]` | `null` | Phone numbers to unassign from this agent. |
| `direction` | `string` | `inbound` | Deployment slot: `inbound`, `outbound`, or `both`. |
Publishing is blocked while instructions are generating, and blocked when instructions are stale (dirty and not manually edited) — regenerate first.
```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/$AGENT_ID/versions/3/publish \
-H "Authorization: Bearer $ANYREACH_TOKEN" \
-H "X-Anyreach-Org: $ANYREACH_ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"phone_numbers": ["+14155551234"],
"direction": "inbound"
}'
```
Drop the `X-Anyreach-Org` header when using an organization API key (`ak_`) — it carries its organization implicitly.
## SIP deployment
Expose an agent over SIP at `sip:@`. The agent must have at least one published version first.
| Method | Path | Scope | Description |
| -------- | --------------------------------- | ------ | ----------------------------------------------------------------------------- |
| `POST` | `/core/agents/{id}/deploy-as-sip` | manage | Deploy the agent as a SIP endpoint. Returns `409` if no version is published. |
| `DELETE` | `/core/agents/{id}/deploy-as-sip` | manage | Remove the agent's SIP endpoint. Returns `204`. |
## Scaffolding agents
These endpoints kick off background workflows that build an agent for you. Each returns `202` with a `workflow_id`.
| Method | Path | Scope | Description |
| ------ | ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST` | `/core/agents/create-from-website` | manage | Build an agent from a company website. Body: `company_name`, `company_website` (required), plus optional `company_overview`, `is_demo`, `skip_deployment`, `voice_id`, `avatar_url`, `existing_agent_id`, `existing_collection_id`, `demo_type`. |
| `POST` | `/core/agents/create-demo` | manage | Build a demo agent. Body: `company_website` (required), plus optional `instructions` and `include_phone_number`. |
## The config contract
`AgentConfig` is the full shape of a version's `config`. The authoritative contract is published as JSON Schema:
| Method | Path | Scope | Description |
| ------ | --------------------------- | ----- | -------------------------------------------------- |
| `GET` | `/core/agent-config-schema` | read | Return the complete JSON Schema for `AgentConfig`. |
Use this endpoint to validate a `config` before sending it to `POST /core/agents/{id}/versions` or `PUT /core/agents/{id}/versions/{version}`, rather than hard-coding field names.
What agents, versions, and publishing mean in the product.
Credentials, the `X-Anyreach-Org` header, and scopes.