Public vs. private agents
Every agent in Tiny Talk is public by default. A public agent accepts messages from anyone without authentication — this is how the embedded chat widget works on your website. When you make an agent private, every request must include a valid API key. Private agents reject unauthenticated requests with a401 Unauthorized response.
| Agent visibility | API key required? | Use case |
|---|---|---|
| Public | No | Website chat widget, open-access assistants |
| Private | Yes | Server-to-server integrations, internal tools, controlled access |
You can change an agent’s visibility in the dashboard under Settings → General.
API key
To authenticate API requests, include your API key in theapi-key header:
Getting your API key
Open the dashboard
Go to dashboard.tinytalk.ai and select your agent.
Navigate to Integrations
Click Integrations in the sidebar, then scroll find Hub → Tiny Talk section.
API key benefits
Requests authenticated with a valid API key:- Can access private agents
- Bypass rate limiting — no per-user message throttling
- Are identified as trusted server-to-server traffic
Rate limiting
Unauthenticated requests (public agents without an API key) are rate-limited per user based on the agent’s rate limit settings. When the limit is exceeded, the API returns a429 status code with rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait before retrying |
Error format
All errors return a JSON response with a status code and message:| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request — invalid or missing parameters |
401 | Unauthorized — invalid or missing API key for a private agent |
403 | Forbidden — plan limit exceeded (messages or model access) |
429 | Rate limited — too many requests |
500 | Internal server error |