Agents API

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. For the product concepts behind these endpoints, see Agents.

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.

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:<agent-id>@<your-sip-uri>. 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.

Agents

What agents, versions, and publishing mean in the product.

Authentication

Credentials, the X-Anyreach-Org header, and scopes.

Get Started

Agents

Conversations

Conversation attachments

Conversation events

Knowledge bases

Knowledge base sources

Sources

Phone numbers

Trunks

Inbound routing

Agent assist

Human handoff

Email domains

Email addresses

Unsubscribes

Web widgets

Campaigns

Campaign contacts

Campaign configurations

Campaign stats

Custom data

Metrics

Evaluations

Evaluation runs

Workflows

Workflow triggers

Workflow executions

Workflow credentials

Scopes

Agents

Versions

Publish a version

SIP deployment

Scaffolding agents

The config contract

Agents

Authentication

​Scopes

​Agents

​Versions

​Publish a version

​SIP deployment

​Scaffolding agents

​The config contract

Agents

Authentication

Scopes

Agents

Versions

Publish a version

SIP deployment

Scaffolding agents

The config contract