API reference
Every endpoint, grouped by what it works on. Each page shows the required scope, the parameters, and a real example response. Authenticate with a Bearer API key.
Core
- Channels5 endpointsA channel connects a chatbot to a messaging platform — telegram, whatsapp, facebook (Messenger), instagram, slack, discord, line, viber, wechat or sms (Twilio) — so the chatbot answers people there. A chatbot has at most one channel per platform, addressed by the platform name.
- Chat2 endpointsPOST /chat runs one chat turn: a visitor message in, the chatbot's reply out, both stored as one message of a conversation. POST /chat/stream runs the same turn and streams the reply as server-sent events. Each turn is billed a message credit, so send an Idempotency-Key: a retry with the same key never runs or bills a second turn.
- Chatbots16 endpointsA chatbot (an agent in the dashboard) is the unit everything else hangs off: knowledge is trained into one, conversations happen with one, and its widget, hosted agent page and messaging channels each serve one.
- Widget11 endpointsThe widget is the chat bubble a website embeds for a chatbot. Its look and behaviour live in the chatbot's settings; the sites it may load on are the chatbot's allowlist of hostnames (alloweddomains). An empty allowlist lets it load on any site; otherwise the page's host must match an entry exactly, or as a subdomain of a .example.com entry. The widget serves only an active chatbot.
Knowledge
- Collections8 endpointsA knowledge collection groups datasets. A collection bound to a chatbot (chatbotid) holds that chatbot's knowledge: the datasets filed in it belong to that chatbot. A collection with chatbotid: null is an account-level folder bound to no chatbot.
- Crawlers26 endpointsA crawler collects a website's pages into knowledge, one dataset per page. There are two kinds, each with its own paths and ids: a website crawler (/crawlers) follows links from a start URL within the depth and page limits you set; a sitemap crawler (/sitemapcrawlers) fetches the pages a sitemap.xml lists, and is the better choice when the site has one.
- Files4 endpointsA file is a document you upload with POST /files to turn it into knowledge with POST /knowledge (name and fileid). Uploading stores it and emits file.created; it trains nothing until a dataset is created from it. Accepted: txt, pdf, doc, docx, rtf and odt documents, png, jpg, jpeg and webp images (read by OCR, as are scanned PDFs) and xlsx, xls, csv and ods spreadsheets — at most 10 MB each, and 20 files or 90 MB per batch, by default. The content must match the extension.
- Knowledge24 endpointsA knowledge dataset is one source a chatbot answers from: text you send, an uploaded file, a web page, a cloud document or a page a crawler collected. The platform extracts its text, cuts it into chunks and embeds them; the chatbot then retrieves those chunks to answer.
- Search2 endpointsPOST /search runs the retrieval a chatbot uses to answer — vector search over trained knowledge (fused with keyword search where that is enabled), then reranking when the reranker is on — and returns the best-matching chunks with their scores, without generating an answer. Use it to check what a chatbot will find for a question, or to build your own search. GET /search/similar/{datasetId} searches inside one dataset.
Conversations
- Analytics1 endpointAnalytics is the account's chat activity over the last 7, 30 or 90 days: daily series, period totals with the period before for comparison, and breakdowns by answer status, rating and chatbot — the figures of the dashboard home page, computed live on each call.
- Conversations8 endpointsA conversation is one thread between a visitor and a chatbot, from any surface: POST /chat, the website widget, the hosted agent page, the dashboard Test Chat or a messaging channel. Each turn in it — the visitor's message and the reply — is a message.
- Customers11 endpointsA customer is one person a chatbot can reach back — by email, phone or your own externalid — kept as one profile per chatbot. Profiles come from chat and from you: the lead form of the widget and the hosted agent page (source: widget), the dashboard Test Chat (dashboard), a collectinfo Call Action (action), a visitor message that is only contact details (chatintent), and POST /customers (api).
Automation
- Actions10 endpointsA Call Action is a tool one chatbot may use mid-conversation. The chatbot's model reads the action's description and, turn by turn, decides whether to call it and with which arguments. There are six types: button (shows the visitor a link button), handoff (flags the conversation for a human and emails your team), notify (emails your team a summary), collectinfo (saves the visitor's contact details as a customer), httprequest (calls your HTTPS endpoint and gives the model its answer) and mcp (calls one tool on an MCP server — only where the platform has MCP switched on; GET /actions/types says which types can be created).
- Events3 endpointsAn event is the record of one thing that happened on the account — a chatbot created, a dataset trained, an action run failed — with a type from a fixed catalogue (GET /eventtypes). GET /events is the account's event log: every recorded event, whether or not a webhook endpoint subscribes to it. Sending an event to an endpoint is a separate webhook delivery, one per event and endpoint.
- Webhook deliveries2 endpointsA webhook delivery is one event on its way to one endpoint, with the outcome of its latest attempt. Delivery is at least once: dedupe on the event id (eventid, the Agentency-Event-Id header).
- Webhook endpoints8 endpointsA webhook endpoint is an HTTPS URL of yours that receives events as signed POST requests. It subscribes to event types (enabledevents, or for every type), and each matching event becomes one delivery to it.
Account
- API keys1 endpointAn API key is the credential every authenticated request sends as Authorization: Bearer agylive… (or agytest…): a prefix naming the mode, a public 16-character keyid, and a 32-character secret. Only a hash of the secret is stored; the secret is shown once, when the key is minted.
- Billing and usage5 endpointsRead-only billing: what the account's plan grants, what it has used, and what it was charged. Changing the plan, buying add-ons or credit packs, and the Stripe billing portal stay in the dashboard — they end on Stripe-hosted pages only a person can complete — so there is no billing:write scope.
- Identity1 endpointGET /me identifies the credential: the account the API key belongs to, and the key's own record. It needs no scope, so any working key can call it — use it as a health check for a credential and to read the key's id for self-revocation.
- OpenAPI document1 endpointGET /openapi.json serves this document: the committed OpenAPI 3.1 contract of /v1, generated from the API's own routes and checked against them on every change. An operation or field that is not in it is not part of the contract. No key is needed.
- Profile2 endpointsThe profile is the account owner's contact details: name, company, website, jobtitle, countrycode and a free-text phone. It belongs to the account owner, not to whoever minted the key, so PATCH /me/profile changes what the owner sees in the dashboard. Email cannot be changed through the API.
- Request logs1 endpointA request log row is one /v1 request of the account: method, route pattern, status, duration and error code — never a body, header, query string or secret. It answers "why did my key stop working?" and "which workload is hitting the rate limit?".
- Status1 endpointGET /status is the API's health check: unauthenticated, free of any account data, and limited per client IP. A 200 means the API is serving requests, and version is the contract version every response also sends in the Agentency-Version header.