> ## Documentation Index > Fetch the complete documentation index at: https://docs.sempera.org/llms.txt > Use this file to discover all available pages before exploring further. # Agents > The Agent model, draft -> preview -> publish, immutable versions, rollback. An Agent is Sempera's core product object: an AI employee that answers a business's phone or Web calls. ## Listing agents `GET /v1/agents` (`agents:read`) lists the Agents the credential can see, with the cursor pagination in [Errors and limits](https://docs.sempera.org/errors-and-limits.md). `status` is `active` (the default), `archived` or `all`; any other value is `400 validation_failed` with `field: status`. An Agent that cannot be read at the moment is not dropped: it appears as `{"id", "object": "agent", "status": "needs_repair", "reason"}`, so a list never silently shrinks. ## Shape `GET /v1/agents/{id}` returns the Agent with its stable `id`, `name`, `workspace_id`, `status` (`draft`, `published`, `archived`), the published version pointer, the verification gates, the channels it can speak on, and, on the detail read, its `draft`, `published`, `voice`, `language`, `instructions`, `tools` and `knowledge`. `channels` says where the Agent can be reached: `web_voice`, `web_chat`, and `phone`, which is `true` once a phone number is set up for the Agent (a number bound to it, or a line released through its deployments). It is the same reading as the phone step of the App's launch checklist, and a numbers read that fails never reports a phone. Provider identifiers (the voice platform's pathway or persona ids) are internal and never the Agent's identity. The Agent's `voice` is `{id, name}` (plus `unresolved: true` when Sempera cannot say which engine the stored voice is on), where `id` is the Sempera voice id `GET /v1/voices` lists. A draft takes a voice the same way: `PATCH /v1/agents/{id}/draft` with `{"fields": {"voice": {"id": "voice_...", "name": "..."}}}`. The draft and every version store the underlying voice that id stands for, so a published version keeps speaking with exactly the voice it was built with. ## Draft, preview, publish Every Agent has one editable **draft** and a ledger of immutable **published versions**. | Step | Route | Notes | | - | - | - | | Read the draft | `GET /v1/agents/{id}/draft` | `editable_fields` lists the keys a PATCH may carry; their current values and choices are the named sections of `GET /v1/agents/{id}` (`instructions`, `voice`, `guardrails`, ...) | | Edit the draft | `PATCH /v1/agents/{id}/draft` | `{"fields": {...}, "expect_revision": "..."}`; a stale revision is refused with `409 conflict` and the current revision | | Discard the draft | `DELETE /v1/agents/{id}/draft` | | | Typed preview | `POST /v1/agents/{id}/preview` | One caller turn against the draft (default) or the published version; carry `session_id` to continue | | Web voice preview | `POST /v1/sessions` | Always the published version | | Publish | `POST /v1/agents/{id}/publish` | Decides, applies and compiles: a new immutable version. Accepts `Idempotency-Key` | | Versions | `GET /v1/agents/{id}/versions`, `GET /v1/agents/{id}/versions/{version_id}` | Never mutated. `{version_id}` is a version's id or its number; a version this agent does not have is `404 not_found` | | Deployments | `GET /v1/agents/{id}/deployments` | The release ledger on the voice platform | | Releases across agents | `GET /v1/release-deployments` | `deploy:read`. Every version put on an environment, for every Agent the credential can see, newest first, with cursor pagination. Each row is a `release_deployment` with `agent_id`, `agent_name`, `workspace_id`, `version_id`, `version_number`, `environment` (`staging`, `production` or `practice`), `action` (`draft`, `promotion` or the ledger's own kind), `status`, `by` and `at` | | Rollback | `POST /v1/agents/{id}/rollback` | `{"to_deployment_id": "..."}` creates a NEW rollback record; history is never rewritten | Production calls and sessions always run a published version. Secrets never appear in a version read; tool authentication is reported as a secret reference, configured or not. ## Lifecycle `POST /v1/agents/{id}/archive` hides an agent, and `POST /v1/agents/{id}/unarchive` brings it back (`agents:write` for both). Each answers the Agent with an `archive` result, and a refusal is `409 conflict` with a sentence saying why. `DELETE /v1/agents/{id}` with `{"confirm": ""}` removes the record, its conversations and its number bindings; it is refused while a version is live. ## Publishing roles Publishing needs `agents:publish` on the key and the `owner` role in the workspace. An operator can edit and preview the draft; only an owner can make it live. ## Contact card and business identity An agent has a contact card and owner-provided business details: `display_name`, `legal_name`, `phone`, `email`, `website`, `address`, `country` and `registration_number`. Reads need `agents:read`; writes need `agents:write` and the `owner` role. | Route | Does | | - | - | | `GET /v1/agents/{agent_id}/identity` | Reads `{profile, verification, revision}`. | | `PUT /v1/agents/{agent_id}/identity` | Saves the whole `profile` with the `revision` you read; a stale revision is `409 conflict`. Changing the profile resets verification to `unverified`. | | `POST /v1/agents/{agent_id}/identity/verification` | Records a review request for the `revision` you read. It needs legal name, address, country and registration number. | | `GET /v1/agents/{agent_id}/identity/vcard` | Downloads the card as `text/vcard`. | | `POST /v1/agents/{agent_id}/identity/send-test` | Checks the delivery boundary for a `to` number. It always answers `503 owner_setup_required` with `sent: false`: nothing is sent. | `verification.status` is `unverified` or `pending_review`. A review request is not a verified badge, `verified_at` stays `null`, and no client can mark a business verified. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.