Circles agent API
API by Circles · rest
Send your key on every request: Authorization: Bearer <key>. An agent handed a one-time code instead (it starts circ_code_) first exchanges it for its key at POST /api/v1/connect/exchange, the one call with no Authorization. Every GET returns JSON. Only chats opened by the person are reachable. To send, reply or react, GET the chat's or message's details and perform one of its actions: a complete request (method, url, headers, body) to which you add only your Authorization header. A write is bound to the exact target you inspected (its target_version) and is a deliberate POST of JSON. Poll voting is unsupported. Version 2.0.0 (2026-10-27) removed browser agents: no browser session or cookie is accepted, the details no longer carry compose_url, reply_url or react_url (their forms are gone; use actions), and a 401 no longer carries login_url (it names the header to send). Version 2.1.0 (2026-11-01): a newly connected number opens its chats for reading and writing by default, there is…
Endpoint: https://app.usecircles.app/
Verification: observed. Source: crawl.
Capabilities (19)
- Which open chats moved since a moment in time: for each how many messages …
- The chats this person opened to agents with the level of access each one…
- Read messages from an open chat with chat_ref (preferred) or chat or read…
- Review the exact currently authorized recipient and obtain a server-issued…
- Send one message to a chat that is open for sending (allowed_chats says read…
- Every document (PDF Word sheet) sent in an open chat since a moment:…
- Acquire one explicitly requested attachment using its announced ref.
- Who is in one open group from WhatsApp's own member list: everyone including…
- Download an already available attachment with current authorization; active…
- Read current attachment state without initiating acquisition.
- Show an already available PDF image audio or video inline in the browser…
- Review one authorized stored message.
- Capability-gated reaction to the exact original provider key.
- Capability-gated native quoted reply.
- The people in the open chats since a moment: for each person the personal…
- Find who to send to by phone number (with its country code) or saved contact…
- Search the text of one open chat or of EVERY open chat when chat is left out…
- Read an authorized submission's receipt without retrying delivery.
- Exchange the one-time code from the person's WhatsApp message for your key.