Agents API

Manage chat agents programmatically — create and configure agents, manage their knowledge sources, tools, and secrets — and integrate the public chat/voice endpoints that power the embeddable widget.

API key management

Create a key, then use it from your backend

Open in TIA

Open API keys and create a named key

Create one key per service or environment so it can be identified and revoked independently.

Copy a server-side example

Use the cURL, JavaScript, or Python request example and keep the key out of browser code.

There are two groups of endpoints:

• Admin endpoints (/api/{organization}/agents/...) — authenticated with an API key; the key's user must be an owner or admin of the organization. These return the standard { success, data } envelope.
• Public endpoints (/api/agents/{publicSlug}/...) — unauthenticated, used by the embedded widget in the browser. They are gated by the agent's public access toggle and allowed origins rather than an API key.

Admin Endpoints Overview

{organization} is your organization's slug or ID (see Organizations API).

Authentication

* Send either x-api-key or Authorization. The key's user must be an owner or admin of the organization. See Authentication.

List Agents

Endpoint: GET /api/{organization}/agents

curl -X GET https://tia.tdccommerce.com/api/acme-inc/agents \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent_abc123",
        "name": "Acme Support Bot",
        "slug": "acme-support-bot",
        "publicSlug": "agt_pub_xxxxxxxxxxxxxxxx",
        "modelType": "agent-chat-v1"
      }
    ]
  }
}

Create Agent

Endpoint: POST /api/{organization}/agents

Body

curl -X POST https://tia.tdccommerce.com/api/acme-inc/agents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Support Bot", "systemPrompt": "You are Acme'\''s support assistant." }'

A unique publicSlug is generated automatically.

Update Agent

Endpoint: PATCH /api/{organization}/agents/{agentId}

Send any subset of these fields:

curl -X PATCH https://tia.tdccommerce.com/api/acme-inc/agents/agent_abc123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowedOrigins": ["https://example.com"] }'

Delete Agent

Endpoint: DELETE /api/{organization}/agents/{agentId}

Deletes the agent and cascades to its sources, tools, and conversations.

Knowledge Sources

List: GET /api/{organization}/agents/{agentId}/sources Add: POST /api/{organization}/agents/{agentId}/sources Delete: DELETE /api/{organization}/agents/{agentId}/sources/{sourceId}

Adding a source accepts one of these shapes (the source is then queued for crawling, chunking, and embedding):

{ "type": "url",  "name": "Help docs",  "url": "https://example.com" }
{ "type": "text", "name": "Returns FAQ", "text": "Our return policy is…" }
{ "type": "qa",   "name": "FAQ",         "qa": [{ "question": "…", "answer": "…" }] }

For a url source, if a sitemap is detected the whole site is indexed automatically.

Tools

List: GET /api/{organization}/agents/{agentId}/tools Create: POST /api/{organization}/agents/{agentId}/tools Get / Update / Delete: …/tools/{toolId} (GET / PATCH / DELETE) Dry-run: POST /api/{organization}/agents/{agentId}/tools/{toolId}/test

Tool fields

The dry-run endpoint runs the exact execution path without writing an audit record and returns the resolved request (with secret-looking values masked) plus a response snippet, so you can validate your templates and response mapping.

Secrets

List (masked): GET /api/{organization}/agents/{agentId}/secrets Create: POST /api/{organization}/agents/{agentId}/secrets Delete: DELETE /api/{organization}/agents/{agentId}/secrets?id={secretId}

Secrets are organization-scoped and encrypted; plaintext is never returned. Reference them in tool templates as {{secret:NAME}}.

curl -X POST https://tia.tdccommerce.com/api/acme-inc/agents/agent_abc123/secrets \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "STRIPE_API_KEY", "value": "sk_live_…" }'

Chat (admin)

Endpoint: POST /api/{organization}/agents/{agentId}/chat

Send a conversation and receive a streamed response. Body:

{
  "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Hi" }] }],
  "conversationId": "optional"
}

The response is a server-sent event stream of message parts. The visitor and conversation identifiers are returned in the X-Visitor-Id and X-Conversation-Id response headers. Chat is credit-gated — if the organization is out of credits the agent returns a fixed "currently unavailable" message.

Public Endpoints

These power the embedded widget and are called from the browser. They require no API key, but the agent must have public access enabled and the request's Origin must be in the agent's allowed origins (the dashboard origin is always allowed).

{publicSlug} is the agent's public slug, the same value used in the embed snippet's data-agent attribute. In normal use you don't call these directly — the embeddable widget does. If the origin isn't allowed, config reports it so you can diagnose embed issues, and chat/voice-token are refused.

Next Steps

• Chat Agents — the full feature guide.
• Voice Assistant and Live Handoff.
• Authentication — sending API keys.