Agents API

An agent has an editable draft and immutable published versions. Calls select a published version ID.

Read agents and versions

Requires agents:read.

Method	Path	Result
GET	/v1/agents	Array of agents
GET	/v1/agents/{agent_id}	Agent metadata
GET	/v1/agents/{agent_id}/editor	Agent metadata and editable draft
GET	/v1/agents/{agent_id}/draft	Draft configuration
GET	/v1/agents/{agent_id}/versions	Array of published versions
GET	/v1/agents/{agent_id}/versions/{version_id}	One published version

The collection endpoints accept limit from 1 to 100 and an optional after cursor. Use the last returned record’s ID to request the next page. Do not assume the first item is the version your deployment should use; explicitly retain the selected version ID.

Create and edit

Requires agents:write.

POST /v1/agents
Content-Type: application/json

{"name":"Reception assistant","description":"Guest inquiries and staff follow-up"}

This creates an agent, not a running call or complete published configuration. Use PATCH /v1/agents/{agent_id} to update its name or description. Use PATCH /v1/agents/{agent_id}/draft to edit configuration sections.

The simplest supported setup is to finish the draft in the dashboard, select compatible providers/models/voices, and publish it there. Never place provider secrets in instructions or provider parameter fields.

Publish

POST /v1/agents/{agent_id}/versions publishes a complete draft. Ordinary EVA publication returns the immutable version. A managed publication may return an asynchronous operation; it is not a usable version until successful.

Use the id from a completed EVA version in POST /v1/conversations. Changing a draft or publishing another version does not rewrite existing versions.

Delete

DELETE /v1/agents/{agent_id} requires agents:write and returns 204 on success. Check calling connections before deleting an agent.

Errors for another workspace’s IDs do not grant access to that workspace’s records.