> ## 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.

# Programmatic agents

> Create, update, and publish agents from the API.

Anyreach exposes a complete REST API for agent management. Use it to:

* Provision agents from CI/CD as part of an environment promotion
* Migrate prompts from a config repo to production
* Run A/B tests on prompt variants

For the full endpoint reference see [Agents API](/api-reference/agents/overview).

## Authentication

All endpoints require a bearer credential. See [Authentication](/getting-started/authentication).

```bash theme={null}
export ANYREACH_TOKEN=...
```

## Create an agent

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents \
  -H "Authorization: Bearer $ANYREACH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Riverside Dental Scheduler",
    "description": "Books appointments for Riverside Dental.",
    "active": true
  }'
```

The response includes the new `agent_id`. The agent starts as a stub — no version, no config — until you create a version.

## Create a version

Versions hold the actual config (voice, model, prompt, tools, knowledge bases).

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/$AGENT_ID/versions \
  -H "Authorization: Bearer $ANYREACH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "config": { ... } }'
```

<Note>
  The agent `config` object is large and strongly typed. Fetch its authoritative JSON Schema from `GET /core/agent-config-schema` rather than hand-writing it, and use the dashboard's agent builder to generate a valid config to start from.
</Note>

The version is created in **draft** state.

## Publish a version

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/$AGENT_ID/versions/$VERSION/publish \
  -H "Authorization: Bearer $ANYREACH_TOKEN"
```

To assign the published version to a phone number, include `phone_numbers` and a `direction` (`inbound`, `outbound`, or `both`) in the publish body. See [Assigning agents to numbers](/telephony/assigning-agents-to-numbers).

## Update an existing draft

To iterate on a draft without creating a new version:

```bash theme={null}
curl -X PUT https://api.anyreach.ai/core/agents/$AGENT_ID/versions/$VERSION \
  -H "Authorization: Bearer $ANYREACH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "config": { ... } }'
```

You can only update **draft** versions. Published versions are immutable; create a new draft to iterate.

## Auto-generate instructions

If you have a purpose description but want Anyreach to draft the conversation flow:

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/$AGENT_ID/versions/$VERSION/generate-instructions \
  -H "Authorization: Bearer $ANYREACH_TOKEN"
```

Generation runs asynchronously. Poll the version with `GET /core/agents/$AGENT_ID/versions/$VERSION` until generation completes.

## Deploy as SIP

For BYOC setups, expose the agent as a SIP endpoint (requires at least one published version):

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/$AGENT_ID/deploy-as-sip \
  -H "Authorization: Bearer $ANYREACH_TOKEN"
```

The agent's `GET` response then includes a `sip_endpoint` object with the SIP URI to point your trunk at. See [SIP trunking and BYOC](/telephony/sip-and-byoc).

## Idempotent provisioning pattern

For CI/CD, the safe pattern is:

```
GET /core/agents?name=$NAME
  ├─ found:   PUT  /core/agents/{id}/versions/{draft}      (update config)
  └─ missing: POST /core/agents                            (create stub)
                  POST /core/agents/{id}/versions           (create draft)

POST /core/agents/{id}/versions/{draft}/publish            (always publish)
```

This reaches the same end state regardless of whether the agent already existed.