Create an agent
Create a brand-new agent in a workspace and return its handle. Pass channel "voice" (the default) for a phone agent, "text" for a website chat agent, or "both" for one that does both; ask the operator which, never guess it. The channel is what the agent serves (set_agent_channels changes it later): website chat is billed per reply and needs a model priced for it. A voice agent is born with the house scaffold (the standard system-prompt template with [bracketed] slots to fill in, a pinned greeting, the starter tools end_call and transfer_to_human, and the universal baseline eval). A text agent is born with the chat scaffold (short written replies, markdown links, no spoken-form rules), a written greeting, no starter tools, the text baseline eval, and its chat panel on and call pill off; the phone-only validator checks skip it. A "both" agent is born with the house scaffold and its chat panel on. Either way it is an editable draft (version 1) you can immediately shape with the other tools; the name is set here, no set_name needed. Pass the operator's IANA timezone (for example Europe/Dublin); omitted, the agent inherits the workspace timezone and answers "are you open now" for that zone. Callers that previously relied on a new agent having an empty prompt must now pass systemPrompt explicitly ("" gives the old blank start). The agent starts unpublished; call publish_version when it's ready.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/workspaces/string/agents" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{
"agent": "string",
"id": "string",
"property1": null,
"property2": null
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Archive an agent DELETE
Archive this agent. A reversible soft-delete that hides it from the workspace agents list and takes the agent off the phone. Archiving unassigns the agent's phone number. The agent stops taking new calls shortly afterwards, not the moment you confirm. The number stays in the workspace as a spare and is NOT released to the provider. Calls already in flight aren't affected, and the agent stays reachable by URL. If the unassign after the archive fails, the agent stays archived and the result says what is still routed to it. Reverse it with `restore_agent`, which does not re-assign the number: point it back with `assign_phone_number`. To remove an agent for good (irreversible), use `permanent_delete_agent` instead.
Duplicate an agent POST
Copy this agent into a new agent, in the same workspace or in the one `workspace` names, and return the new agent's handle. `agent` is the SOURCE to copy; `name` is the new agent's display name (its slug is derived from the name). Pass `workspace` to move an agent to another workspace you hold workspace-wide edit access in: the copy carries everything below, and the original keeps its calls, phone numbers and lead callback until you move them. Copied: the source's latest version content (system prompt, inbound, returning and outbound greetings, workflow, model and version settings) as an unpublished draft version 1, every tool row (order, kind, parameters, HTTP endpoint and headers, mocks, requires, follow-up, response template), every variable (plain, secret and default-only; secret values are stored again server-side for the new agent and never returned), and the agent-row call-handling config (settings, model, realtime, voice, keyterms, PII and retention). Copying the variables needs edit access to the source; the result lists the copied variable names and kinds under `variablesCopied`. When any variable is not copied, `variablesError` says why and `variablesNotCopied` lists every such name with its reason; the rest are still copied, so re-enter only those. NOT copied: tests and scenarios, phone numbers, the public share link, and knowledge-base sources. The duplicate starts unpublished and takes no calls until you call publish_version. Use it to fork a working agent for a second location or a variant you want to change without touching the original, or to hand an agent to another workspace; use create_agent instead when you want the house scaffold.