Skip to main content
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. 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. 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": "<id>"} 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. 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.