REST API: agents
Create, inspect, update, and delete agents from a trusted backend.
Use the Agents REST endpoints to run an agent's full lifecycle from your own backend. List agents, or create an agent. Then store the returned identifier in your service. Before you update an agent, fetch its current resource. Keep each update narrow. A configuration change, an avatar removal, and a deletion are different actions. Each action has different recovery expectations.
Deletion is an administrative operation. Before you request a deletion, make sure that the organization and the agent identifier are correct. Record the deletion in your own audit trail. You can cancel a pending deletion with the dedicated endpoint. Do not assume that another kind of update reverses a deletion. An avatar removal deletes only the avatar. It does not delete the agent or its configured knowledge.
Two fields on the create response decide whether the agent can appear on a website. id addresses the agent in every later REST call. publicId is the value the embed snippet's data-agent-id attribute takes. POST /agents without an isPublic field creates a public agent, because the endpoint leaves the field unset and the column default of true applies. Send "isPublic": false to create a private agent, and PATCH /agents/{id} to change it later. collectLeads behaves differently: omit it and the agent does not collect leads.
name holds 1 to 200 characters. AgentStack trims the leading and trailing spaces, then measures the length and saves the trimmed name. A name of spaces alone is therefore refused with Name cannot be empty or only whitespace. The same bound holds on the dashboard and on the MCP create_agent and update_agent tools, so a name that one door accepts is accepted at all three. An agent created before this bound existed can hold a longer name. PATCH /agents/{id} refuses a patch that echoes that name back, so send a shorter name, or omit the field.
Three fields on PATCH /agents/{id} are reserved for an owner or an admin: sessionResumeHours, geoRestrictionMode and geoRestrictionCountries. An API key carries no organization role, so a request that sends any of them is refused with 403 and the error code FORBIDDEN, whatever scope the key holds. Change those three from the dashboard, or from the MCP update_agent tool signed in as an admin. Every other field in the body is accepted with a write-scope key. Send the admin-only fields in their own request, so a refusal never costs you the rest of the patch.
The shapes still hold when an admin sends them. sessionResumeHours is an integer from 1 through 168. The REST field does not accept 0, even though the dashboard offers Always new session. geoRestrictionCountries accepts null or up to 250 two-letter country codes. The API removes exact duplicate codes after it validates the input count. A request with more than 250 array entries is therefore refused even when some entries repeat.
Use a write-scope key for routine changes. Use a more privileged key for destructive actions. Parse the standard response envelope. Log the error codes. Do not retry authorization errors or validation errors. For setup parameters and exact payloads, see the generated reference. This guide describes the lifecycle workflow. It does not replace the schema catalog.