REST API: agents

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. A restored agent counts toward the plan's agent limit again, so the cancellation is refused with 403 and the error code AGENT_LIMIT_REACHED when the organization already has as many active agents as its plan allows. 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 invisible characters from both ends (spaces, zero-width and other format characters, and control characters), then measures the length and saves the trimmed name. A name with no visible character is refused with 400 VALIDATION_ERROR and Name must contain at least one visible character. A name that contains a null character (U+0000) or a bidirectional control character (U+202A–U+202E, U+2066–U+2069) is also refused with 400 VALIDATION_ERROR. 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. The MCP update_agent tool takes 0 through 168 for the same field, so 0 is how an admin selects Always new session outside the dashboard. That tool holds the REST bounds on the widget fields too: up to 5 initial messages of 500 characters each, a floating message of 200 characters, a floating-message delay of 1 to 30 seconds, and up to 4 suggested messages of 60 characters each. 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.

Set the widget appearance

PATCH /agents/{id} accepts themeConfig with a write-scope key. It is the same object that the dashboard's Settings → Appearance page saves: theme (light, dark or system), position (bottom-right or bottom-left) and an optional primaryColor. The object replaces the stored one, so send theme and position every time. Omit primaryColor to go back to the default blue #0a84ff.

primaryColor is the widget's brand colour. It must be a 6-digit hex code such as #c2185b. Any other value is refused with 400, and nothing in the patch is saved. AgentStack stores the colour in lower case. The launcher, the visitor's messages, the send button and links in replies use it. A pale colour is accepted as it is: the widget then draws near-black text on it, and darkens reply links until they are readable.

Choose a model

GET /mcp/models lists every model that an agent can use. Each item gives the id, the display name, the provider, the credits that one reply costs, and permittedOnCurrentPlan. Send the id as model on POST /agents or PATCH /agents/{id}. The list does not include retired model ids. A model with permittedOnCurrentPlan: false is refused on your current plan. The route is read-only, spends no credits, and is also the MCP tool list_models.

An unsupported model id is refused with the error code MODEL_NOT_SUPPORTED. The error message ends with Call list_models for valid ids.

Changes

• 2026-10-10 — PATCH /agents/{id} accepts themeConfig, with the widget brand colour primaryColor. A colour that is not a 6-digit hex code is refused with 400.
• 2026-09-24 — New route GET /mcp/models lists the models that an agent can use, with the credit cost of each and whether your plan permits it.
• 2026-09-24 — The MODEL_NOT_SUPPORTED error message on POST /agents and PATCH /agents/{id} ends with Call list_models for valid ids. The error code did not change.