Skip to main content
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

ActionRequired scope
Read agents and versionsagents:read (or agents:manage)
Create, update, delete, publish, deployagents:manage
Read endpoints accept either agents:read or agents:manage. Every write, publish, and deploy endpoint requires agents:manage.

​
Agents

MethodPathScopeDescription
GET/core/agentsreadList agents. Filter by name, active, is_demo, metadata (JSON object string), and created_*/updated_* timestamps. Paginate with limit and cursor.
POST/core/agentsmanageCreate an agent. Body: name (required), description, active (default true), is_demo (default false), metadata.
GET/core/agents/{id}readGet one agent, including its versions, assigned phone numbers, widgets, SIP endpoint state, and conversation statistics.
PUT/core/agents/{id}manageUpdate an agent’s name, description, active, is_demo, or metadata.
DELETE/core/agents/{id}manageDelete 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.
MethodPathScopeDescription
GET/core/agents/{id}/versionsreadList an agent’s versions. Filter by version, published, and created_*/updated_* timestamps. Paginate with limit and cursor.
GET/core/agents/{id}/versions/{version}readGet one version. version is a number or the literal latest. Requesting latest ensures a draft exists.
POST/core/agents/{id}/versionsmanageCreate 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}manageUpdate an unpublished version’s config or instruction_builder_inputs. Returns 400 if the version is published.
POST/core/agents/{id}/versions/comparereadStream 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-instructionsmanageStart 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}/publishmanagePublish 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.
FieldTypeDefaultDescription
phone_numbersstring[]nullPhone numbers to assign this version to.
unassign_phone_numbersstring[]nullPhone numbers to unassign from this agent.
directionstringinboundDeployment 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.
MethodPathScopeDescription
POST/core/agents/{id}/deploy-as-sipmanageDeploy the agent as a SIP endpoint. Returns 409 if no version is published.
DELETE/core/agents/{id}/deploy-as-sipmanageRemove 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.
MethodPathScopeDescription
POST/core/agents/create-from-websitemanageBuild 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-demomanageBuild 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:
MethodPathScopeDescription
GET/core/agent-config-schemareadReturn 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.