Authentication

API keys, scopes, rate limits and errors.

The public API lives at https://threadbox.ai/api/public/v1. Authenticate every request with a workspace API key in the Authorization header.

bash

curl https://threadbox.ai/api/public/v1/chatbots \
  -H "Authorization: Bearer sk_live_…"

Creating keys #

Go to Settings → API keys. Keys start with sk_live_ and are shown once. They belong to a workspace, not a user, so they keep working when people leave. Revoke a key at any time; revoked keys fail with 401 immediately.

Keep keys server-side

Never ship an API key in a browser or mobile app. For visitor-facing chat use the widget, or proxy the chat endpoint through your own backend.

Scopes #

Scope	Grants
`read`	List chatbots, conversations, messages, leads and source summaries.
`write`	Add or replace knowledge sources and trigger reindexing.
`chat`	Send messages to an agent and receive replies.

Rate limits #

120 requests per minute per key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds). Over the limit you get 429 with a Retry-After header. Chat calls also count towards the monthly conversation allowance of the workspace.

Errors #

Errors are JSON with a stable code:

json

{
  "status": 403,
  "code": "FORBIDDEN",
  "message": "This key is missing the \"write\" scope"
}

Status	Meaning
400	Validation failed - details lists field errors.
401	Missing, malformed or revoked key.
403	Scope missing, plan lacks API access, or conversation allowance reached.
404	Resource not in this workspace.
429	Rate limited.
5xx	Something broke on our side; safe to retry with backoff.