Skip to content
Chatvia Docs
On this page

API reference

Agents

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints create and manage agents. An agent is the assistant your visitors chat with: its name, its instructions and who may open its chat.

For example, an agency that sets up a support agent for each new client can create the agent from its own onboarding tool, then add the client's help pages as sources.

What the API can change on an agent is the name, the instructions, whether the chat is public, and your own metadata. Everything else, such as the model, branding and surfaces, is set on the agent's Setup page in the dashboard.

Read the overview first for the base URL, keys, errors and paging.

The agent object

json
{
  "id": "a3f9c2e17b4d08",
  "team": { "id": "0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01", "name": "Support" },
  "name": "Help Desk",
  "is_public": true,
  "metadata": { "crm_account": "ACME-1042" },
  "source": "api",
  "system_instructions": "You answer questions about our shop. Keep answers short.",
  "prompt_id": null,
  "slug": "a3f9c2e17b4d08",
  "url": "https://chat.example.com/chat/a3f9c2e17b4d08",
  "permanent_url": "https://chat.example.com/chat/a3f9c2e17b4d08",
  "created_at": "2026-10-25T09:14:03+00:00",
  "updated_at": "2026-10-25T09:14:03+00:00"
}
Field Type Meaning
id string The agent's id, 14 letters and digits. It is the data-agent-id of the embed code.
team object The team the agent belongs to: its id and name.
name string The name shown in the dashboard and in the chat header.
is_public boolean true when anyone can open the chat. false when the chat needs a sign-in. See Protected agents.
metadata object Your own key and value pairs, such as an id from your CRM. Chatvia sends it to your functions in the X-Chatvia-Metadata header.
source string api when the agent was created through the API, dashboard otherwise.
system_instructions string or null The instructions that steer how the agent answers, also called the system prompt. null when the agent uses a saved prompt.
prompt_id string or null The saved prompt from your prompt library that the agent uses instead, if any.
slug string or null The last part of the chat address. It changes when someone renames the address in the dashboard.
url string The chat address, built from the slug. When the agent has an active custom domain, it is that domain, such as https://help.yourshop.com.
permanent_url string A chat address built from the id. It keeps working when the slug changes. It is the custom domain too, when the agent has one.
created_at, updated_at string When the agent was created and last changed.

List agents

Returns the agents you can reach, newest first.

text
GET /api/v1/agents

Who can call it: anyone with a key. The owner sees every agent. A teammate sees only the agents their role reaches.

Query parameter Type Required Notes
team_id string no Only list the agents of this team. An unknown team is a 422.
per_page, cursor no See Pagination.
bash
curl "https://chat.example.com/api/v1/agents?team_id=0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01" \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [agent, …], "next_cursor": … } with agent objects.

Create an agent

Creates a new agent in one of your teams.

text
POST /api/v1/agents

Who can call it: the workspace owner only.

Body field Type Required Notes
name string yes 3 to 255 characters.
team_id string yes The id of the team the agent goes in. List teams with List teams.
is_public boolean yes true for a chat anyone can open. false for a chat that needs a sign-in.
system_instructions string no Up to 10,000 characters. Can't be sent together with prompt_id.
prompt_id string no The id of a saved prompt. See List prompts. Can't be sent together with system_instructions.
metadata object no Your own key and value pairs.
bash
curl https://chat.example.com/api/v1/agents \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Desk",
    "team_id": "0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01",
    "is_public": true,
    "system_instructions": "You answer questions about our shop. Keep answers short.",
    "metadata": { "crm_account": "ACME-1042" }
  }'

The answer is 201 Created with { "data": agent }.

Good to know:

  • The new agent gets a new id. Its chat address uses that id until someone sets a friendlier address in the dashboard.
  • The agent starts with your workspace's conversation topics attached.
  • The model, branding and surfaces start with their defaults. Change them on the agent's Setup page.

Get an agent

Returns one agent.

text
GET /api/v1/agents/{agent}

Who can call it: anyone with access to the agent.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": agent }.

Update an agent

Changes the fields you send. A field you leave out keeps its value.

text
PATCH /api/v1/agents/{agent}

Who can call it: the owner, or a teammate with Setup agent.

Body field Type Notes
name string 3 to 255 characters.
is_public boolean Switches the chat between public and sign-in only.
system_instructions string or null Up to 10,000 characters. Sending it removes the saved prompt from the agent.
prompt_id string or null A saved prompt. Sending it clears system_instructions. Can't be sent together with system_instructions.
metadata object or null Replaces the whole metadata object.
bash
curl -X PATCH https://chat.example.com/api/v1/agents/a3f9c2e17b4d08 \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt_id": "0199f3b0-4a2d-7e11-8c3b-2d4e5f6a7b8c" }'

The answer is { "data": agent } with the new values.

Delete an agent

Deletes the agent.

text
DELETE /api/v1/agents/{agent}

Who can call it: the owner, or a teammate with Delete agent.

bash
curl -X DELETE https://chat.example.com/api/v1/agents/a3f9c2e17b4d08 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content.

This can't be undone

The agent is gone at once: its chat address and API routes stop working right away. Its conversations, its uploaded files and the sources no other agent uses are then removed in the background. Your workspace functions and connectors stay. Only their link to this agent is removed.

List prompts

Returns the saved prompts of your prompt library, newest first. Use a prompt's id as prompt_id when you create or update an agent. The prompts themselves are written on the dashboard's prompt library page. See Prompts library.

text
GET /api/v1/prompts

Who can call it: the owner, or a teammate with Prompts. Without it the answer is 404.

bash
curl https://chat.example.com/api/v1/prompts \
  -H "Authorization: Bearer $CHATVIA_API_KEY"
json
{
  "data": [
    {
      "id": "0199f3b0-4a2d-7e11-8c3b-2d4e5f6a7b8c",
      "name": "Friendly support",
      "prompt": "You are a friendly support assistant. Answer from the sources only.",
      "created_at": "2026-09-14T11:20:00+00:00"
    }
  ],
  "next_cursor": null
}

Search guides, settings and commands.