Introduction - Talqing

The Talqing API is a JSON HTTP API at https://api.talqing.com, every path under /v1. Everything the dashboard does to agents, tools, calls and conversations goes through it, and both SDKs and the MCP server are generated from the same OpenAPI document.

Your first request

Send a personal access token as Authorization: Bearer <token>. Create one in the dashboard under Organization → API Tokens; it acts as you, with your current role. See authentication.

curl https://api.talqing.com/v1/agents \
  -H "Authorization: Bearer $TALQING_API_KEY"

import { TalqingClient } from "@talqing/sdk";

const talqing = new TalqingClient({
  baseUrl: "https://api.talqing.com",
  token: process.env.TALQING_API_KEY,
});

const agents = await talqing.agents.list();
console.log(agents.items.map((agent) => agent.config.name));

import os
from talqing import Talqing

with Talqing(token=os.environ["TALQING_API_KEY"], base_url="https://api.talqing.com") as talqing:
    agents = talqing.agents.list()
    print([agent["config"]["name"] for agent in agents["items"]])

Response

{
  "items": [
    {
      "id": "9c2f1a44-3d0b-4a6e-8f21-5b7c0e93a4d1",
      "config": { "name": "Support line", "channel": "voice" },
      "published_version": 3,
      "published_at": "2026-08-28T11:02:19.401882Z",
      "created_at": "2026-08-21T09:14:22.792290Z",
      "updated_at": "2026-08-28T11:02:19.401882Z"
    }
  ],
  "has_more": false,
  "limit": 200,
  "offset": 0
}

Conventions

Convention	Rule
Content type	`application/json` in and out. Send `Content-Type: application/json` with every body.
Ids	Bare UUID strings. No prefixed ids.
Timestamps	ISO 8601 UTC: `2026-08-30T15:49:30.792290Z`.
Lists	Always the `Page` envelope (`items`, `has_more`, `limit`, `offset`), never a bare array. See pagination.
Creates	`201` with the created resource.
Deletes	`200` with `{"ok": true}`, except where an endpoint’s reference says otherwise.
Errors	One envelope at every status: `{"detail": {"message", "errors"}}`. See errors.
Rate limits	None. No endpoint returns `429`.
Health	`GET /health` is the only unauthenticated endpoint and reports the API process only, not its dependencies.

PATCH merges

A PATCH changes only the fields you send.

PATCH /v1/agents/{agent_id} and PATCH /v1/tasks/{task_id} merge config key by key, including nested objects such as llm. A list (tools, handoffs, faqs) replaces the stored one whole: to add an entry, send the full list. An unknown field is refused. See updating an agent.
PATCH /v1/tools/{tool_id} replaces operations whole. Send every operation you want to keep.
Every PATCH is a JSON merge patch: an omitted field is unchanged, and an explicit null clears a field the schema marks nullable — {"label": null} removes a phone number’s label. null on a field that cannot be empty, such as a tool’s name, is a 422 naming the field.

Agent, tool and task writes land on the draft. Live traffic keeps the published version until you publish again — see versions.

Validate and publish

Every validate endpoint answers 200 with {"errors": [...], "warnings": [...]}. Errors block a publish, warnings do not. POST /v1/agents/{agent_id}/publish runs the same checks and refuses with 400 if any error remains; a successful publish returns the warnings.

Endpoint tags

The Endpoints section is generated from openapi.json, grouped by tag:

Tag	Covers
`agents`	Agent drafts, published versions, rollback
`tools`	Custom tools and operation trees
`tasks`	Agent tasks and their runs
`faqs`	Question/answer lists agents and tasks answer from
`calls`	Call tokens, outbound calls, call batches, call history, recordings
`chats`	Text sessions: start, message, stream, end
`conversations`	The per-person thread across channels, its sessions and items
`telephony`	Carrier accounts, phone numbers, media streams
`email`	Senders and email batches
`whatsapp`	Templates and WhatsApp batches
`integrations`	External services, MCP servers, triggers
`observability`	Workspace volume, cost and latency analytics
`webhooks`	Subscriptions and delivery logs
`secrets`	Workspace secrets for tools
`byok`	Your provider keys
`catalog`	Providers, models, voices, avatars
`billing`	Credit balance, ledger, checkout
`copilot`	AgentCoPilot, ToolCoPilot and TaskCoPilot conversations
`schemas`	Full definitions of the large request types — see schemas
`service`	`GET /health`

Sign-in, workspace membership, invites and personal access tokens are dashboard-only endpoints and are not in this reference or the SDKs.

Errors

The error envelope, every status code, what to retry.

SDKs

TypeScript and Python clients generated from this document.

​Your first request

​Conventions

​PATCH merges

​Validate and publish

​Endpoint tags