HTTP API
A WhatsApp API for your personal number
Circles gives your scripts, n8n workflows and own agents the WhatsApp chats you choose, as JSON over HTTP with a key. It works with your existing personal number, with no WhatsApp Business account and no bridge to run. It reads by default and writes only where you allow.
Circles is an HTTP API for a personal WhatsApp number: link your number as a linked device, make a key, and call https://app.usecircles.app/api/v1/agent with Authorization: Bearer circ_..., described in OpenAPI 3.1 at https://app.usecircles.app/api/openapi.json. It reads the chats you opened, voice notes as text, and, on Pro, sends, replies and reacts only where you allowed sending. Circles is free for 2 chats, or $29 a month on Pro (₪99 in Israel) with 14 days free, as of October 2026.
Updated
The API at a glance
| Circles HTTP API | |
|---|---|
| Base URL | https://app.usecircles.app/api/v1/agent |
| Auth | Authorization: Bearer <key>: a key made on the Agents page (circ_...) or an MCP client's OAuth token. No cookies. |
| Spec | OpenAPI 3.1 at https://app.usecircles.app/api/openapi.json; a readable reference at https://app.usecircles.app/api |
| Format | JSON. Times in UTC, as milliseconds (at) and ISO 8601 (at_iso) |
| Paging | Follow pagination.next_url until it is null; has_more says if there is more. Each page re-checks what the key may reach. |
| Same as MCP | The nine operations, the same chats, the same permissions and cap |
| Only in the API | Quoted replies, emoji reactions, write receipts, finding or starting a chat by number |
| Your number | Your personal WhatsApp, as a linked device. No WhatsApp Business, no second number. |
From signup to the first call
Link your WhatsApp in Circles
Start your trial, then link your number as a linked device: a code typed on your phone, or a QR on your computer. Same number, same WhatsApp on your phone. History arrives in about 5 to 15 minutes, and you can connect your agent meanwhile.
Make a key
On Circles' Agents page, choose New token, pick the agent (or Other), choose API with a key, what it allows, and how long it works: no limit, 90 days or a year.
Hand it over in two messages
Circles gives you instructions without the key, then the key on its own, so the key goes only into the agent's secrets. For a script or n8n, paste the key straight into your credentials.
Make the first call
GET https://app.usecircles.app/api/v1/agent/allowed_chatswithAuthorization: Bearer circ_.... That list is the whole world the key can reach.
Two reads, with the key in an environment variable:
curl -s "https://app.usecircles.app/api/v1/agent/allowed_chats" \
-H "Authorization: Bearer $CIRCLES_KEY"
curl -s "https://app.usecircles.app/api/v1/agent/catch_up?since=2026-10-26T00:00:00Z" \
-H "Authorization: Bearer $CIRCLES_KEY"Endpoints
All under /api/v1/agent unless shown. The OpenAPI document has every parameter and response.
| Endpoint | What it does |
|---|---|
GET allowed_chats | The chats open to this key and what it may do in each. The whole world. |
GET activity | Which chats moved since a time: counts, last time, last sender, no text |
GET catch_up | Messages since a time, one chat or all, senders by name, voice notes with their transcript. kind=voice|audio|recording filters. |
GET search | Text search in one chat or all, including what was said in voice notes |
GET people | Who you talk with across open chats, and where |
GET group_members | Members of one open group, by name, admins marked, never numbers |
GET documents | Every PDF, Word file and sheet sent in open chats, with its state |
POST get_media | One attachment; asks your phone to re-upload an older one if needed |
GET media/{ref}/status, content, view | An attachment's state, its bytes, or the file for showing in a browser |
GET chats/{chat_ref}, messages/{message_ref} | Details, with the complete actions you may take there |
POST chats/{chat_ref}/messages | Send text, a file, or a file with a caption |
POST messages/{message_ref}/replies | A native quoted reply. API only. |
POST messages/{message_ref}/reactions | An emoji reaction. API only. |
GET writes/{submission_ref} | The read-only receipt of a write |
GET recipients?to= | Find a chat by number or exact saved name, or start one, when your number allows starting chats |
POST /api/v1/connect/exchange | Swaps a one-time connect code for a key (how Instinct connects). The one call with no Authorization. |
Sending, replies and reactions
A chat's or a message's details carry its actions: complete requests with method, URL, headers and body. Perform one as given, add your Authorization header, and fill in only the text, file or emoji.
- Idempotent. Each write carries a submission reference Circles issued, bound to its target. Reusing it within 24 hours cannot send again or take another slot of the daily cap.
- Never retried. If the answer is
delivery_unknown, check the receipt atwrites/{submission_ref}and the chat before you decide to send again. A message that may have left is never sent twice by Circles. - Only where allowed. Sends, replies and reactions all need the key's send permission and a chat open for sending, and all count against the same daily cap. A refusal says what is missing and what is still allowed.
- Quotes fail closed. A reply that cannot be quoted is refused.
- Not supported: voting in polls, removing a reaction, quoting a message that is not text.
Sending a file: add it to the body the send action gives you. A JPEG, PNG or WebP arrives as a photo, an MP4 as a video, anything else as a document under its filename.
"text": "Signed copy attached",
"file": {
"mime": "application/pdf",
"data_base64": "<the file, base64, up to about 3 MB>",
"filename": "nda.pdf"
}Voice notes and files
A voice note (kind: voice) or audio file (kind: audio) carries its transcript, transcribed automatically in Hebrew and English, so you read what was said without fetching the audio. transcript_state says pending while it is still being written.
Other attachments come as an announcement: filename, type, size and a status_url, plus content_url once Circles holds the file. Circles serves the bytes, and your code reads the PDF or image. Files older than about 25 days at linking come from your phone on request: POST to acquire_url, and the phone, if it is online, re-uploads the file.
Limits
| Limit | Value |
|---|---|
| Text message | Up to 65,536 characters |
| Caption | Up to 4,096 characters |
| File to send | About 3 MB |
| File to fetch | Up to 50 MB each |
| Daily send cap | Per number, across all agents together: default 5; 5, 10, 20 or no cap; counted per UTC day |
| Write idempotency | 24 hours per submission reference |
| Key lifetime | No limit (default), 90 days or a year; revocable at once |
| One-time connect code | Single use, one hour, ten tries a minute per address |
More on limits and errors: the API and MCP documentation.
n8n, scripts, and agents you built
- n8n: an HTTP Request node with a header credential,
Authorization: Bearer circ_.... This reaches your personal chats. n8n's own WhatsApp node is for WhatsApp Business accounts. - Scripts: a morning digest of three groups, an export of every document sent in a project chat, a weekly count of who asked you what. Plain GETs, JSON back.
- Your own agent: anything that calls HTTP. The instructions Circles gives with the key tell an agent how to read, page and act, and that a send is never retried.
- Dots connects this way too: instructions first, then its key in a message of its own.
Prefer MCP? The same chats and permissions are at https://app.usecircles.app/api/mcp: the WhatsApp MCP hub.
Questions and answers
Does personal WhatsApp have an API?
WhatsApp offers an official API only for WhatsApp Business. Circles gives your personal number an HTTP API by linking it as a linked device and serving only the chats you open, with a key.
Is this the WhatsApp Business API?
No. The Business API is Meta's official way for businesses to message customers, on a business number. Circles works with your personal number and your existing chats. The difference in detail.
Can I use it with n8n?
Yes. Use an HTTP Request node with the header Authorization: Bearer circ_... and the base URL https://app.usecircles.app/api/v1/agent. n8n's built-in WhatsApp node is for Business accounts.
Will a retry send the same message twice?
No. Each write carries a submission reference, and reusing it within 24 hours cannot send again or use another cap slot. If delivery is uncertain, Circles says so and never retries on its own.
Can WhatsApp disconnect my number for this?
Linked-device access by an unofficial client is outside WhatsApp's terms, and no one can promise a device is never logged out. Circles reads by default, caps sends, never broadcasts, and connects each customer through a dedicated IP address shared with no other customer.
What does it cost?
The API is in every Circles plan: Free, Starter at $9.90 a month, and Pro at $29 a month (₪99 in Israel) with 14 days free. Sending through the API is on Pro.
Connect your WhatsApp to your agent today.
14 days free. Link your number, pick the chats, then connect Instinct with one tap or Claude, ChatGPT and Codex with one address.