Get started

API introduction

Chat with your agent, add knowledge and read conversations, leads and contacts from your own code.

The AnytimeReply REST API lets your backend talk to your agents: send customer messages and get answers, add knowledge, and read conversations, leads and contacts. It uses the same brain as the chat bubble — knowledge, Q&A, instructions, actions and handoff.

Base URL

Text

https://anytimereply.com/api/v1

Requests and responses are JSON (Content-Type: application/json). Timestamps are ISO 8601 in UTC.

Authentication

Create a key under Settings → API keys (account owners only; your email must be confirmed). The full key is shown once — store it safely. You can have up to 10 active keys and revoke any of them; apps using a revoked key stop working immediately.

Send the key with every request, either way:

HTTP

Authorization: Bearer af_live_xxxxxxxxxxxxxxxxxxxxxxxx

HTTP

X-API-Key: af_live_xxxxxxxxxxxxxxxxxxxxxxxx

A key gives access to every agent of your workspace. Keep it on your server — never in a browser, mobile app or public repository.

Never call the API directly from your website's JavaScript: anyone could read your key. Call it from your server, or use the chat bubble for the browser.

Agent IDs

Most endpoints take an agent's ID (a UUID such as 3f2c…). Find it in:

Settings → API keys → Your agent IDs,
the dashboard address when you open an agent (/dashboard/agents/AGENT_ID), or
GET /api/v1/agents.

The public key in the chat bubble code (shown as Agent ID under the agent's Settings → General) identifies the agent to the website chat. The REST endpoints under /api/v1 need the ID; the OpenAI-compatible API and the MCP server accept either.

Quick example

curl https://anytimereply.com/api/v1/chat \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID", "message": "Do you deliver to Sylhet?", "user_id": "customer-42"}'

Endpoints

Method	Path	What it does
`POST`	/api/v1/chat	Send a message, get the agent's answer (optionally streamed)
`GET`	/api/v1/agents	List your agents
`GET`	/api/v1/agents/{id}/conversations	List conversations
`GET`	/api/v1/conversations/{id}	One conversation with its messages
`GET`	/api/v1/agents/{id}/leads	Leads and form submissions
`GET`	/api/v1/agents/{id}/sources	Knowledge sources and training status
`POST`	/api/v1/agents/{id}/sources	Add knowledge
`POST`	/api/v1/agents/{id}/qa	Add a Q&A answer
`GET` `POST`	/api/v1/agents/{id}/contacts	Find, create or update contacts
`GET` `PATCH` `DELETE`	/api/v1/agents/{id}/contacts/{contact}	One contact
`GET` `POST`	/api/openai/v1/…	OpenAI-compatible models and chat completions
`POST`	/api/mcp	MCP server (JSON-RPC over Streamable HTTP)

Errors

Errors return a JSON body with a message and a 4xx/5xx status:

JSON

{ "error": "Agent not found" }

Status	When
`400`	Invalid JSON or a field failed validation — the message names the field, e.g. `message: String must contain at least 1 character(s)`
`401`	Missing, invalid or revoked API key (or the account isn't active)
`403`	Your plan doesn't allow it, e.g. `Training limit of your plan reached`
`404`	The agent, conversation or contact doesn't exist in your workspace
`409`	`Already exists` — a unique value is taken
`413`	The request body is too large (1 MB, or 7 MB for sources)
`429`	Rate limit reached
`500`	Something went wrong on our side — retry later

Rate limits

Each API key can make 120 requests per minute (a fixed one-minute window), shared by the REST API, the OpenAI-compatible API and the MCP server. Over the limit you get 429 with {"error": "Too many requests, please slow down."} — wait until the next minute and retry.

Credits

Calls that produce an AI answer (/chat, OpenAI chat completions, MCP ask_agent) use message credits exactly like the chat bubble. Reading data and adding knowledge don't use credits.

Real-time events

Instead of polling, get a signed POST when a conversation starts, a lead arrives, a chat is handed over or closed, or a customer rates a chat. See Webhooks.

Was this page helpful?

Still stuck? Contact us