API reference on the Developer tab

What it is

The Developer tab holds two things: your API keys, and the Knowledge Ingest API reference — live documentation for the endpoint that pushes text into a chatbot's knowledge base from your own code.

The reference is not a mock. It prints the real endpoint URL for your installation, a parameter table, and copy-ready snippets in curl, JavaScript, and Python. The same component appears inside Add Knowledge → API on a chatbot, where it arrives pre-filled with that chatbot's id.

There is no separate "try it" console that fires requests from the browser. You copy a snippet and run it from your own terminal or code, authenticated with a personal access token.

When you would use it

Open the reference when you want your documentation, your CMS, or your product catalogue to keep a chatbot's knowledge current without anyone pasting text into the dashboard.

Typical shapes: publish a help article and push it the same minute; export a price list nightly; ship a changelog entry as part of your release pipeline.

Where to find it

Open Dashboard → Settings → Developer and scroll past the key table. The card is titled Knowledge Ingest API.

The chatbot-scoped version is at Chatbots → your chatbot → Knowledge → Add → API.

Both are owner-only, because the Developer tab is.

Steps

1. Open Dashboard → Settings → Developer.
2. Create a key with knowledge:write and nothing else, unless you have a reason. See Choose token scopes.
3. Read the endpoint printed on the reference card and copy it with the copy button.
4. Pick your language with the segmented control — curl, JavaScript, or Python — and copy the snippet.
5. Replace the <YOUR_TOKEN> placeholder with your real secret, held in an environment variable rather than pasted into the file.
6. Replace <CHATBOT_ID> with a real id from Dashboard → Chatbots. The settings page has no chatbot context, so it can only show a placeholder; open the reference from inside a chatbot's Add Knowledge drawer and the id is filled in for you.
7. Send the request. A success response confirms the item was created.
8. Open that chatbot's Knowledge tab. The new item appears in the table and moves through training on its own.
9. Once the badge reads trained, ask the chatbot a question that only the new content can answer.

The request

curl -X POST https://api.example.com/v1/knowledge/ingest \
  -H "Authorization: Bearer $AGENTENCY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "chatbot_id": 42,
        "name": "Refund policy 2026",
        "description": "Synced from the handbook",
        "content": "Refunds are issued to the original payment method within 14 days.",
        "auto_train": true
      }'

Use your own API host — see API host — no /api prefix. There is no /api prefix; the /v1 here is part of this route.

Parameter	Type	Required	Notes
chatbot_id	integer	yes	Must be a chatbot in your own account
name	string	yes	The title shown in the Knowledge table and in citations
content	string	yes	The text itself, exactly as you would paste it into the Text tab
description	string	no	A short note for your own reference
collection_id	integer	no	Files the item into an existing collection
auto_train	boolean	no	Defaults to true; send false to add without training yet

What you will see

The reference card shows a POST badge next to the full endpoint URL with a copy button, the parameter table above, a language switcher with the three snippets, and a note that the endpoint requires a key with knowledge:write.

Above it, the key table lists your existing keys. Below it, nothing else — the Developer tab is keys plus this reference, not a full API explorer.

Building a reliable sync

A few habits that make the difference between a sync you trust and one you babysit:

• One source per topic. Push an updated version to the same logical item rather than creating a second one. Two versions of a policy will compete at answer time, and the chatbot has no way to know which is current.
• Send clean text. Extraction is literal. Strip navigation, cookie banners, and repeated footers before you send — they cost knowledge capacity and add noise.
• Name items the way a customer would recognise them. The name appears in citations.
• Handle the response. Check the status and read error.code on failure rather than assuming success. A 422 carries per-field validation reasons.
• Respect the limits. The endpoint is rate-limited and caps how much text one request may carry. Split a large export into several items — which is better for answer quality anyway.
• Watch training, not just the response. A successful ingest means the item was created. The chatbot can only use it once training finishes; see Dataset status and training.

Limits and plan notes

Ingest obeys the same per-chatbot knowledge limit as an upload. An account at its ceiling gets a plan-limit failure rather than a validation error — see Chatbot and knowledge limits.

The endpoint accepts text. Files, PDFs, and images go through the upload path in the dashboard — see Upload files.

This reference documents ingest only. It is not a complete catalogue of every route the API exposes.

Using the reference and pushing knowledge costs no message credits. Credits are spent when the chatbot answers somebody.

Common problems

The snippet still says <CHATBOT_ID>.

The settings page has no chatbot context. Paste a real id from the Chatbots list, or open the same reference from Add Knowledge → API inside a chatbot, where it is pre-filled.

403 with an insufficient-scope error.

The key lacks knowledge:write. Scopes cannot be widened, so create a new key.

422 on chatbot_id.

The id does not belong to your account. Ids are per account, so a chatbot in a client workspace needs a key created by that workspace's owner.

The item was created but the chatbot ignores it.

Check the training badge on the Knowledge tab first. If it is trained and still ignored, the wording is likely the problem — ask using a phrase that appears in the text you sent.

Can I use my dashboard login from a server?

No. Browser sessions are not a supported server credential. Use a personal access token — see Create a personal access token.

Is there a sandbox host?

No. There is one API host per installation. To experiment safely, create a throwaway chatbot and push to that.