The API: authentication and rate limits

The REST API is at /api/v1, on the app host. It reaches the same actions the panel uses: conversations, messages and contacts.

The API is on the Pro plan and up.

Authenticating

A bearer token, which is the API key you created:

curl https://app.talkfront.app/api/v1/conversations \
  -H "Authorization: Bearer tf_…" \
  -H "Accept: application/json"

The key identifies the workspace, so there is no workspace id to pass and no way to reach another one. Everything you can see through the API is scoped to the key you used.

Read and write

A key has read, write, or both. A read key calling a write endpoint is refused; it is not silently ignored.

Give a key the narrower option and widen it if you find you need to. See creating an API key.

Rate limits

Requests are limited per key. Go over it and you get 429 Too Many Requests, with a header saying how long to wait.

Handle that rather than retrying immediately: a client that hammers straight back through a limit stays limited. Wait the period you are given, and back off if it happens repeatedly.

If you are hitting limits in normal use, you are probably polling for something a webhook would tell you. That is what they are for, and it is cheaper at both ends.

Errors

Ordinary HTTP. 401 for a missing or bad key, 402 when your plan does not include the API, 403 when the key lacks the ability, 404 for something that is not there or not yours, 422 for validation, 429 for rate limits.

Validation errors come back with a field-by-field body, the same shape the panel gets.

What it is not for

The API is a server-side interface. It is not for your frontend: a key in browser JavaScript is a published key. To drive the chat window from a page, use the JavaScript API, which is designed for it and carries no credentials.

Last updated 22 September 2026.