Question 1

Is an API key the same as staying signed in?

Accepted Answer

No. Your dashboard session is a browser credential and is not supported from a server. A personal access token is the machine credential, and the two are entirely separate.

Question 2

I closed the dialog without copying the secret.

Accepted Answer

It cannot be recovered — no readable copy is kept. Revoke that key and create another; an uncopied key is just a row in the table doing nothing.

Question 3

What expiry should I choose?

Accepted Answer

The presets are 30, 90 and 365 days, plus a no-expiry option that is really a very distant fixed date. Pick short only if you genuinely have a rotation process, and diary the renewal.

Question 4

Can I put a key in my website's JavaScript?

Accepted Answer

Never. Anything in browser code is readable by anyone. The widget has its own public token and allowed-domain list for exactly this purpose.

Question 5

Does creating or revoking a key affect my dashboard session?

Accepted Answer

No. Key management and browser sign-in are independent, so revoking a leaked key never signs you out.

Question 6

Which scopes can a self-service key hold?

Accepted Answer

knowledge:read, knowledge:write, chatbots:read, chatbots:write, chat:send, widget:manage and billing:read. Anything not on that list is not offered in the create dialog.

Question 7

Which scopes are withheld, and why?

Accepted Answer

Team management, your own account surface, key management, and the internal widget chat scope. A key that could mint keys would make the scope model only one request deep.

Question 8

Can I add a scope to an existing key?

Accepted Answer

No. Scopes are fixed at creation. Create a replacement with the full set, deploy it, then revoke the old key.

Question 9

What scope does a website plugin need?

Accepted Answer

widget:manage alone. It reaches the widget token and the allowed-domain list, and deliberately cannot create, edit or delete a chatbot from a server you do not fully control.

Question 10

Can billing:read spend money?

Accepted Answer

No. It reads plan, subscription and usage figures. There is no write counterpart, so no key can start a checkout, change a plan, or open the payment portal.

Question 11

Where do I find my API base URL?

Accepted Answer

From the endpoint printed on the Knowledge Ingest API card at Settings → Developer, or from the data-api-base-url attribute in your widget embed snippet.

Question 12

Why does everything return 404?

Accepted Answer

Check for an /api prefix in the path first — it is the cause in most reports. Some routes carry their own /v1 segment, but there is never an /api wrapper.

Question 13

I got HTML back instead of JSON.

Accepted Answer

You called the dashboard host, which serves the web app. Point your client at the API host instead.

Question 14

Which error code should my client branch on?

Accepted Answer

The nested error.code in the response body, not the message text, which is localised. 401 is auth, 403 insufficient_scope is a scope gap, 402 is a plan or credit gate, 429 is rate limiting.

Question 15

Does an API chat message spend a message credit?

Accepted Answer

Yes. A chat turn sent through the API is charged exactly like a visitor's message on the widget or hosted page.

Question 16

Is there a browser console that fires requests for me?

Accepted Answer

No. The reference gives you the real endpoint, a parameter table and copy-ready snippets; you run them from your own terminal or code with a personal access token.

Question 17

The snippet still shows a chatbot id placeholder.

Accepted Answer

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.

Question 18

Which scope does the ingest endpoint need?

Accepted Answer

knowledge:write. Grant nothing else unless the job genuinely needs it — a sync that only pushes content has no reason to read or edit chatbots.

Question 19

Can I upload a PDF through the ingest endpoint?

Accepted Answer

No, it accepts text. Files, PDFs and images go through the upload path in the dashboard, which runs extraction and, for scans, transcription first.

Question 20

The call succeeded but the chatbot ignores the content.

Accepted Answer

A successful ingest means the item was created; the chatbot can only use it once training finishes. Check the training badge on the Knowledge tab first.

Question 21

There is no Webhooks section under Developer. Where is it?

Accepted Answer

There is not one. Outbound calls are HTTP request Call actions on a chatbot; inbound deliveries are wired up automatically when you connect a messaging channel.

Question 22

How does my endpoint verify a call really came from Agentency?

Accepted Answer

Enable request signing on the action. Agentency then sends an HMAC-SHA256 of the body in a header you name — hash the raw bytes and compare with a timing-safe function.

Question 23

Why was my URL rejected as a blocked destination?

Accepted Answer

It resolves to a private, internal or link-local address. Only public HTTPS endpoints are called, and the same guard applies to redirects.

Question 24

Do you retry a failed call?

Accepted Answer

Calls are made at most once, and a timeout is ambiguous — your endpoint may have completed the work. Deduplicate on a key you control so an ambiguous outcome cannot double-charge.

Question 25

Can I subscribe to every conversation event?

Accepted Answer

Not today. There is no push feed. Poll the API on a schedule, or capture what you need during the conversation with a Call action.

Question 26

A key has leaked. What do I do first?

Accepted Answer

Revoke it immediately and accept the brief outage, then create a replacement with the narrowest workable scopes. Investigate afterwards — a key you are unsure about is a key to revoke.

Question 27

Can I regenerate the secret on an existing key?

Accepted Answer

No. The plaintext only exists at creation time, so rotation always means creating a new key and revoking the old one.

Question 28

How do I confirm a revocation actually worked?

Accepted Answer

Make one request with the old secret and check you get a 401. If you get a 404 you tested the wrong URL and proved nothing.

Question 29

Everything broke when I rotated. Why?

Accepted Answer

Several systems were sharing one key. Give each system its own from now on — that is what the Name column is for, and it is why the table shows Last used.

Question 30

Does revoking a key remove a connected site?

Accepted Answer

No. Reconnect the plugin with the new key, and tidy the allowed-domain list separately if the site is genuinely going away.

Developer API FAQ