{"openapi":"3.1.0","info":{"title":"Circles agent API","version":"2.0.0","description":"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. Writes require exact target review and 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)."},"servers":[{"url":"/"}],"security":[{"bearerToken":[]}],"tags":[{"name":"Connect"},{"name":"Reads"},{"name":"Targets"},{"name":"Writes"},{"name":"Media"}],"paths":{"/api/v1/agent/allowed_chats":{"get":{"operationId":"allowed_chats","x-query-schema":{"type":"object","properties":{"page_size":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384}},"additionalProperties":false},"tags":["Reads"],"description":"The chats this person opened to agents, with the level of access each one carries. This is the whole world: a chat missing from this list cannot be read, searched or sent to, and asking for it by name will be refused. Call this first when you do not know what is available. A chat the person archived in WhatsApp says archived: true, here and wherever another tool names it (documents lists chat names only, without it). It is still open and readable; archiving is the person setting it aside, not closing it. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Maximum entries per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"chats":{"type":"array","items":{"type":"object","properties":{"chat":{"type":"string"},"kind":{"type":"string"},"account":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"details_url":{"type":"string"},"archived":{"type":"boolean"},"name":{"type":"string"},"access":{"type":"string","enum":["read only","read and send"]}},"required":["kind","name","access"],"additionalProperties":{}}}},"required":["chats"],"additionalProperties":{}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/activity":{"get":{"operationId":"activity","x-query-schema":{"type":"object","properties":{"since":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"page_size":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384}},"required":["since"],"additionalProperties":false},"tags":["Reads"],"description":"Which open chats moved since a moment in time: for each, how many messages, when the last one was, and who sent it. Counts only, no text, so it is the cheap first call for 'what happened', 'anything I missed', 'who wrote to me'. Then catch_up on the chats that matter, or catch_up with no chat for all of them at once. `last_at` and `last_at_iso` are UTC. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Maximum entries per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"chats":{"type":"array","items":{"type":"object","properties":{"chat":{"type":"string"},"kind":{"type":"string"},"account":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"details_url":{"type":"string"},"archived":{"type":"boolean"},"messages":{"type":"integer"},"last_at":{"type":"number","description":"Milliseconds since 1970-01-01, UTC."},"last_at_iso":{"description":"The same moment in ISO 8601, UTC.","type":"string"},"last_from":{"type":"string"}},"required":["chat","messages","last_at","last_from"],"additionalProperties":{}}}},"required":["chats"],"additionalProperties":{}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/people":{"get":{"operationId":"people","x-query-schema":{"type":"object","properties":{"since":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"limit":{"description":"Legacy alias of page_size; do not combine them.","type":"integer","minimum":1,"maximum":150},"min_messages":{"type":"integer","minimum":1,"description":"Leave out people with fewer messages than this (default 3), unless they share two small groups with the person."},"page_size":{"description":"Maximum entries per page (default 50, cap 150).","type":"integer","minimum":1,"maximum":150},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384}},"required":["since"],"additionalProperties":false,"allOf":[{"not":{"required":["limit","page_size"]}}]},"tags":["Reads"],"description":"The people in the open chats since a moment: for each person, the personal chat with them (how many messages, how many from the person you work for, when last) and the open groups they are in, with how many messages they wrote in each (0 for a member who never wrote; membership comes from each group's member list). Someone is listed after min_messages messages, or when they share at least two small groups (under 50 members) with the person you work for; members of big groups who barely write are left out. Names are their saved contact names where known. Counts only, no text. Use it to map someone's life: who is close, who is family (the family groups), who is a parent from the kids' gan (the gan groups), who is work. Each person includes a bounded summary of up to eight groups; more_groups reports omitted groups and groups_summary_limit is 8. This is not an exhaustive membership listing. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},{"name":"limit","in":"query","required":false,"schema":{"description":"Legacy alias of page_size; do not combine them.","type":"integer","minimum":1,"maximum":150},"description":"Legacy alias of page_size; do not combine them."},{"name":"min_messages","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Leave out people with fewer messages than this (default 3), unless they share two small groups with the person."},"description":"Leave out people with fewer messages than this (default 3), unless they share two small groups with the person."},{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50, cap 150).","type":"integer","minimum":1,"maximum":150},"description":"Maximum entries per page (default 50, cap 150)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"people":{"type":"array","items":{"type":"object","properties":{"person":{"type":"string"},"account":{"type":"string"},"saved_contact":{"type":"boolean"},"personal_chat":{"type":"object","properties":{"chat":{"type":"string"},"kind":{"type":"string"},"account":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"details_url":{"type":"string"},"archived":{"type":"boolean"},"messages":{"type":"integer"},"from_you":{"type":"integer"},"last_at":{"type":"number","description":"Milliseconds since 1970-01-01, UTC."},"last_at_iso":{"description":"The same moment in ISO 8601, UTC.","type":"string"}},"required":["chat","messages","from_you","last_at"],"additionalProperties":{}},"groups":{"type":"array","items":{"type":"object","properties":{"chat":{"type":"string"},"kind":{"type":"string"},"account":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"details_url":{"type":"string"},"archived":{"type":"boolean"},"messages":{"type":"integer"}},"required":["chat","messages"],"additionalProperties":{}}},"more_groups":{"type":"integer"}},"required":["person","saved_contact","groups"],"additionalProperties":{}}},"more_people":{"type":"integer"},"groups_summary_limit":{"type":"integer"}},"required":["people"],"additionalProperties":{}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/catch_up":{"get":{"operationId":"catch_up","x-query-schema":{"type":"object","properties":{"since":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"chat":{"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both.","type":"string","minLength":1,"maxLength":2000},"limit":{"description":"Legacy page_size alias, valid only with chat or chat_ref. Do not combine with page_size.","type":"integer","minimum":1,"maximum":200},"per_chat":{"type":"integer","minimum":1,"maximum":50,"description":"Without a chat: how many messages per chat at most (default 20, hard cap 50). The NEWEST are kept."},"kind":{"type":"string","enum":["voice","audio","recording"],"description":"Only messages that are this: voice (a WhatsApp voice note, spoken), audio (an audio file) or recording (either)."},"page_size":{"description":"Maximum entries per page (default 50, cap 200). Without an exact chat/name the cap is 100 chat blocks.","type":"integer","minimum":1,"maximum":200},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}},"required":["since"],"additionalProperties":false,"allOf":[{"if":{"not":{"anyOf":[{"required":["chat"]},{"required":["chat_ref"]}]}},"then":{"properties":{"page_size":{"maximum":100}},"not":{"required":["limit"]}}},{"not":{"required":["chat","chat_ref"]}},{"not":{"required":["limit","page_size"]}}]},"tags":["Reads"],"description":"Read messages from an open chat with chat_ref (preferred) or chat, or read every open chat that moved when neither is supplied. Single-chat pages are newest-page first with messages oldest first within each page. All-chat results include independent messages_pagination and messages_url links per chat, as well as the outer pagination.next_url. Navigate each complete continuation URL to exhaust it. Attachments are announced with refs and states; file bytes are never included in message reads. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},{"name":"chat","in":"query","required":false,"schema":{"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both.","type":"string","minLength":1,"maxLength":2000},"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both."},{"name":"limit","in":"query","required":false,"schema":{"description":"Legacy page_size alias, valid only with chat or chat_ref. Do not combine with page_size.","type":"integer","minimum":1,"maximum":200},"description":"Legacy page_size alias, valid only with chat or chat_ref. Do not combine with page_size."},{"name":"per_chat","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"description":"Without a chat: how many messages per chat at most (default 20, hard cap 50). The NEWEST are kept."},"description":"Without a chat: how many messages per chat at most (default 20, hard cap 50). The NEWEST are kept."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["voice","audio","recording"],"description":"Only messages that are this: voice (a WhatsApp voice note, spoken), audio (an audio file) or recording (either)."},"description":"Only messages that are this: voice (a WhatsApp voice note, spoken), audio (an audio file) or recording (either)."},{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50, cap 200). Without an exact chat/name the cap is 100 chat blocks.","type":"integer","minimum":1,"maximum":200},"description":"Maximum entries per page (default 50, cap 200). Without an exact chat/name the cap is 100 chat blocks."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."},{"name":"chat_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"anyOf":[{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"chat":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"attachments":{"type":"object","properties":{"count":{"type":"integer"},"note":{"type":"string"}},"required":["count","note"],"additionalProperties":false},"order":{"type":"string","enum":["oldest_first_within_page","newest_first"]},"page_direction":{"type":"string","const":"older"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"number","description":"When it was sent: milliseconds since 1970-01-01, UTC."},"at_iso":{"description":"The same moment in ISO 8601, UTC (ends in Z). Nothing is converted to a local time.","type":"string"},"body":{"type":"string"},"from":{"type":"string"},"fromMe":{"type":"boolean"},"type":{"type":"string"},"media":{"type":"object","properties":{"ref":{"type":"string"},"message_id":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string","description":"What the attachment is: image, video, voice (a WhatsApp voice note, spoken), audio (an audio file), document or sticker."},"mime":{"type":"string"},"filename":{"type":"string"},"size":{"type":"string"},"size_bytes":{"type":"number"},"fetch_with":{"type":"string","const":"get_media"},"status_url":{"description":"GET: this attachment's current state and links.","type":"string"},"content_url":{"description":"GET: download the file. Null until Circles holds it.","type":["string","null"]},"view_url":{"description":"GET: show the file in the browser (PDF, image, audio, video). Null until stored, and for other types.","type":["string","null"]},"acquire_url":{"description":"POST {ref}: ask the person's phone to re-upload a file WhatsApp no longer serves. Then GET content_url.","type":"string"},"unavailable":{"type":"boolean"},"note":{"type":"string"},"transcript":{"description":"What a voice note or audio file says, transcribed by Circles.","type":"string"},"transcript_state":{"description":"Audio only: pending (being transcribed), done, empty (no speech) or failed.","type":"string","enum":["pending","done","empty","failed"]},"duration_seconds":{"description":"Voice notes and audio files: how long it is, in seconds, as WhatsApp reported it. Absent where it did not.","type":"integer","minimum":0}},"required":["ref","message_id","state","kind","mime"],"additionalProperties":{}},"reactions":{"description":"Present only when someone reacted: each person's current reaction, oldest first.","type":"array","items":{"type":"object","properties":{"emoji":{"type":"string","description":"One emoji."},"from":{"type":"string","description":"Who reacted, by the name a sender is shown with; you for this number."},"fromMe":{"type":"boolean"},"at":{"type":"number","description":"When it was set: milliseconds since 1970-01-01, UTC."},"at_iso":{"type":"string","description":"The same moment in ISO 8601, UTC (ends in Z)."}},"required":["emoji","from","fromMe","at","at_iso"],"additionalProperties":false}},"message_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"chat":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"archived":{"type":"boolean"},"details_url":{"type":"string"},"chat_details_url":{"type":"string"}},"required":["id","at","body","from","fromMe"],"additionalProperties":{}}}},"required":["messages"],"additionalProperties":{}},{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"chat":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"attachments":{"type":"object","properties":{"count":{"type":"integer"},"note":{"type":"string"}},"required":["count","note"],"additionalProperties":false},"order":{"type":"string","enum":["oldest_first_within_page","newest_first"]},"page_direction":{"type":"string","const":"older"},"chats":{"type":"array","items":{"type":"object","properties":{"chat":{"type":"string"},"kind":{"type":"string"},"account":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"details_url":{"type":"string"},"archived":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"number","description":"When it was sent: milliseconds since 1970-01-01, UTC."},"at_iso":{"description":"The same moment in ISO 8601, UTC (ends in Z). Nothing is converted to a local time.","type":"string"},"body":{"type":"string"},"from":{"type":"string"},"fromMe":{"type":"boolean"},"type":{"type":"string"},"media":{"type":"object","properties":{"ref":{"type":"string"},"message_id":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string","description":"What the attachment is: image, video, voice (a WhatsApp voice note, spoken), audio (an audio file), document or sticker."},"mime":{"type":"string"},"filename":{"type":"string"},"size":{"type":"string"},"size_bytes":{"type":"number"},"fetch_with":{"type":"string","const":"get_media"},"status_url":{"description":"GET: this attachment's current state and links.","type":"string"},"content_url":{"description":"GET: download the file. Null until Circles holds it.","type":["string","null"]},"view_url":{"description":"GET: show the file in the browser (PDF, image, audio, video). Null until stored, and for other types.","type":["string","null"]},"acquire_url":{"description":"POST {ref}: ask the person's phone to re-upload a file WhatsApp no longer serves. Then GET content_url.","type":"string"},"unavailable":{"type":"boolean"},"note":{"type":"string"},"transcript":{"description":"What a voice note or audio file says, transcribed by Circles.","type":"string"},"transcript_state":{"description":"Audio only: pending (being transcribed), done, empty (no speech) or failed.","type":"string","enum":["pending","done","empty","failed"]},"duration_seconds":{"description":"Voice notes and audio files: how long it is, in seconds, as WhatsApp reported it. Absent where it did not.","type":"integer","minimum":0}},"required":["ref","message_id","state","kind","mime"],"additionalProperties":{}},"reactions":{"description":"Present only when someone reacted: each person's current reaction, oldest first.","type":"array","items":{"type":"object","properties":{"emoji":{"type":"string","description":"One emoji."},"from":{"type":"string","description":"Who reacted, by the name a sender is shown with; you for this number."},"fromMe":{"type":"boolean"},"at":{"type":"number","description":"When it was set: milliseconds since 1970-01-01, UTC."},"at_iso":{"type":"string","description":"The same moment in ISO 8601, UTC (ends in Z)."}},"required":["emoji","from","fromMe","at","at_iso"],"additionalProperties":false}},"message_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"chat":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"archived":{"type":"boolean"},"details_url":{"type":"string"},"chat_details_url":{"type":"string"}},"required":["id","at","body","from","fromMe"],"additionalProperties":{}}},"more":{"type":"integer"},"messages_pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"messages_url":{"type":["string","null"]},"order":{"type":"string"},"page_direction":{"type":"string"}},"required":["chat","messages"],"additionalProperties":{}}},"chats_with_messages":{"type":"integer"},"truncated":{"type":"string"}},"required":["chats"],"additionalProperties":{}}]},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/search":{"get":{"operationId":"search","x-query-schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"Case-insensitive text to search for."},"chat":{"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both.","type":"string","minLength":1,"maxLength":2000},"days":{"type":"integer","minimum":1,"maximum":36500,"description":"How far back to look, in days. Leave it out to search everything kept: the full history by default, or the account's window if the person narrowed it."},"kind":{"type":"string","enum":["voice","audio","recording"],"description":"Only messages that are this: voice (a WhatsApp voice note, spoken), audio (an audio file) or recording (either)."},"page_size":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}},"required":["query"],"additionalProperties":false,"allOf":[{"not":{"required":["chat","chat_ref"]}}]},"tags":["Reads"],"description":"Search the text of one open chat, or of EVERY open chat when `chat` is left out (each hit then names its chat). It matches what was written and what voice notes and audio files say (their transcript); `kind` narrows the hits to voice, audio or recording. Only chats already open to agents. Use it for 'did anyone mention…'; use catch_up for 'what happened'. Times are UTC: `at` is milliseconds since 1970 and `at_iso` the same moment in ISO 8601 ending in Z. Circles does not know where the person is and converts nothing. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"Case-insensitive text to search for."},"description":"Case-insensitive text to search for."},{"name":"chat","in":"query","required":false,"schema":{"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both.","type":"string","minLength":1,"maxLength":2000},"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":36500,"description":"How far back to look, in days. Leave it out to search everything kept: the full history by default, or the account's window if the person narrowed it."},"description":"How far back to look, in days. Leave it out to search everything kept: the full history by default, or the account's window if the person narrowed it."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["voice","audio","recording"],"description":"Only messages that are this: voice (a WhatsApp voice note, spoken), audio (an audio file) or recording (either)."},"description":"Only messages that are this: voice (a WhatsApp voice note, spoken), audio (an audio file) or recording (either)."},{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Maximum entries per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."},{"name":"chat_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"chat":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"attachments":{"type":"object","properties":{"count":{"type":"integer"},"note":{"type":"string"}},"required":["count","note"],"additionalProperties":false},"order":{"type":"string","enum":["oldest_first_within_page","newest_first"]},"page_direction":{"type":"string","const":"older"},"query":{"type":"string"},"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"number","description":"When it was sent: milliseconds since 1970-01-01, UTC."},"at_iso":{"description":"The same moment in ISO 8601, UTC (ends in Z). Nothing is converted to a local time.","type":"string"},"body":{"type":"string"},"from":{"type":"string"},"fromMe":{"type":"boolean"},"type":{"type":"string"},"media":{"type":"object","properties":{"ref":{"type":"string"},"message_id":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string","description":"What the attachment is: image, video, voice (a WhatsApp voice note, spoken), audio (an audio file), document or sticker."},"mime":{"type":"string"},"filename":{"type":"string"},"size":{"type":"string"},"size_bytes":{"type":"number"},"fetch_with":{"type":"string","const":"get_media"},"status_url":{"description":"GET: this attachment's current state and links.","type":"string"},"content_url":{"description":"GET: download the file. Null until Circles holds it.","type":["string","null"]},"view_url":{"description":"GET: show the file in the browser (PDF, image, audio, video). Null until stored, and for other types.","type":["string","null"]},"acquire_url":{"description":"POST {ref}: ask the person's phone to re-upload a file WhatsApp no longer serves. Then GET content_url.","type":"string"},"unavailable":{"type":"boolean"},"note":{"type":"string"},"transcript":{"description":"What a voice note or audio file says, transcribed by Circles.","type":"string"},"transcript_state":{"description":"Audio only: pending (being transcribed), done, empty (no speech) or failed.","type":"string","enum":["pending","done","empty","failed"]},"duration_seconds":{"description":"Voice notes and audio files: how long it is, in seconds, as WhatsApp reported it. Absent where it did not.","type":"integer","minimum":0}},"required":["ref","message_id","state","kind","mime"],"additionalProperties":{}},"reactions":{"description":"Present only when someone reacted: each person's current reaction, oldest first.","type":"array","items":{"type":"object","properties":{"emoji":{"type":"string","description":"One emoji."},"from":{"type":"string","description":"Who reacted, by the name a sender is shown with; you for this number."},"fromMe":{"type":"boolean"},"at":{"type":"number","description":"When it was set: milliseconds since 1970-01-01, UTC."},"at_iso":{"type":"string","description":"The same moment in ISO 8601, UTC (ends in Z)."}},"required":["emoji","from","fromMe","at","at_iso"],"additionalProperties":false}},"message_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"chat":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"archived":{"type":"boolean"},"details_url":{"type":"string"},"chat_details_url":{"type":"string"}},"required":["id","at","body","from","fromMe"],"additionalProperties":{}}},"searched_days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"truncated":{"type":"string"}},"required":["query","hits"],"additionalProperties":{}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/documents":{"get":{"operationId":"documents","x-query-schema":{"type":"object","properties":{"since":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"page_size":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384}},"required":["since"],"additionalProperties":false},"tags":["Reads"],"description":"Every document (PDF, Word, sheet) sent in an open chat since a moment: filename, date, which chats it was sent to (the same file in several chats is one entry), and whether it can still be fetched. Names and dates only. Fetch one with get_media and its ref; each entry's `state` is the one get_media describes. Good for finding schedules, calendars, forms and agreements. `at` and `at_iso` are UTC. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},"description":"ISO 8601 timestamp; fixed with the query's upper bound for the whole traversal."},{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Maximum entries per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"documents":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"mime":{"type":"string"},"at":{"type":"number","description":"Milliseconds since 1970-01-01, UTC."},"at_iso":{"description":"The same moment in ISO 8601, UTC.","type":"string"},"chats":{"type":"array","items":{"type":"string"}},"copies":{"type":"array","items":{"type":"object","properties":{"chat":{"type":"string"},"kind":{"type":"string"},"account":{"type":"string"},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"details_url":{"type":"string"},"archived":{"type":"boolean"}},"required":["chat"],"additionalProperties":{}}},"size":{"type":"string"},"size_bytes":{"type":"number"},"caption":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"fetchable":{"type":"string"},"ref":{"type":"string"},"message_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."}},"required":["filename","mime","at","chats","state","fetchable","ref"],"additionalProperties":{}}}},"required":["documents"],"additionalProperties":{}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/group_members":{"get":{"operationId":"group_members","x-query-schema":{"type":"object","properties":{"chat":{"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both.","type":"string","minLength":1,"maxLength":2000},"page_size":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}},"additionalProperties":false,"allOf":[{"not":{"required":["chat","chat_ref"]}},{"anyOf":[{"required":["chat"]},{"required":["chat_ref"]}]}]},"tags":["Reads"],"description":"Who is in one open group, from WhatsApp's own member list: everyone, including members who never wrote. Each member is shown by the name the person you work for saved for them, else the name they write under in the group, else their own WhatsApp name marked with ~. Admins are marked. The person you work for is not in the list. Members nobody has a name for are only counted (`unnamed`), and phone numbers are never given. Navigate pagination.next_url until null to read all named members. Joins, leaves and admin changes arrive as they happen; the whole list is re-read every few hours, so a change made while the number was disconnected can take that long to show. Use people for who someone is across all the open chats. HTTP reads use bounded-live keyset pagination. Navigate pagination.next_url unchanged. Membership can change after edits, deletions, permission changes or late imports; this is not a snapshot. Choose chat or chat_ref, never both. group_members requires one of them. limit and page_size are mutually exclusive. people permits 150 per page; single-chat catch_up permits 200; all-chat catch_up and other reads permit 100. The x-query-schema extension describes cross-parameter constraints.","parameters":[{"name":"chat","in":"query","required":false,"schema":{"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both.","type":"string","minLength":1,"maxLength":2000},"description":"An open chat name. Prefer the exact chat_ref from allowed_chats; never supply both."},{"name":"page_size","in":"query","required":false,"schema":{"description":"Maximum entries per page (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Maximum entries per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor.","type":"string","minLength":1,"maxLength":16384},"description":"Opaque continuation from next_url; navigate the complete returned URL instead of constructing a cursor."},{"name":"chat_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"since":{"type":"string"},"note":{"type":"string"},"connection":{"type":"object","properties":{"state":{"type":"string"},"note":{"type":"string"}},"required":["state","note"],"additionalProperties":false},"scope":{"type":"string"},"chats_open":{"type":"integer"},"coverage":{"anyOf":[{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false},{"type":"array","items":{"type":"object","properties":{"account":{"type":"string"},"requested_from":{"type":"string"},"days":{"type":"integer"},"full_history":{"type":"boolean","const":true},"oldest_held":{"type":"string"},"note":{"type":"string"}},"required":["requested_from","days","note"],"additionalProperties":false}}]},"chat":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"admin":{"type":"boolean"}},"required":["name"],"additionalProperties":false}},"members_total":{"type":"integer"},"unnamed":{"type":"integer"},"more_named":{"type":"integer"}},"required":["chat","members","members_total"],"additionalProperties":{}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer","exclusiveMinimum":0},"returned":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_url":{"description":"Complete same-origin URL to navigate, or null when exhausted.","type":["string","null"]},"query_until":{"type":["string","number"]}},"required":["page_size","returned","has_more","next_cursor","next_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data","pagination"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/get_media":{"post":{"operationId":"get_media","tags":["Writes"],"description":"Acquire one explicitly requested attachment using its announced ref. This POST may ask the person's phone to re-upload a missing file and may wait about 25 seconds. Available responses carry download_url (the file itself, GET with no header, valid until expires_at and only while the chat stays open) and, for a file up to 10 MB, bytes_base64. A 202 pending response provides status_url and Retry-After: navigate that read-only status URL to check progress. GET status/content never initiate acquisition. A gone result is terminal. No acquisition is retried automatically.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","description":"The `ref` from an announced attachment in an earlier result. Not a filename."}},"required":["ref"],"additionalProperties":false}}}},"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"anyOf":[{"type":"object","properties":{"ref":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string"},"mime":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"type":"number"},"status_url":{"type":"string"},"content_url":{"type":["string","null"]},"view_url":{"type":["string","null"]},"acquire_url":{"type":"string"},"status":{"type":"string","const":"available"},"bytes_base64":{"description":"Present for a file up to 10 MB.","type":"string"},"download_url":{"description":"The file itself: GET it with no header. It is its own credential, works until expires_at, and only while the chat stays open.","type":"string"},"expires_at":{"description":"When download_url stops working, ISO 8601, UTC. Call get_media again for a new one.","type":"string"}},"required":["ref","state","kind","mime","size_bytes","status_url","content_url","view_url","acquire_url","status"],"additionalProperties":false},{"type":"object","properties":{"ref":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string"},"mime":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"type":"number"},"status_url":{"type":"string"},"content_url":{"type":["string","null"]},"view_url":{"type":["string","null"]},"acquire_url":{"type":"string"},"status":{"type":"string","enum":["pending","gone","too_large","failed"]}},"required":["ref","state","kind","mime","status_url","content_url","view_url","acquire_url","status"],"additionalProperties":false}]},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"202":{"description":"Acquisition is still pending. Navigate Location to read status; acquisition is not automatically retried.","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"anyOf":[{"type":"object","properties":{"ref":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string"},"mime":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"type":"number"},"status_url":{"type":"string"},"content_url":{"type":["string","null"]},"view_url":{"type":["string","null"]},"acquire_url":{"type":"string"},"status":{"type":"string","const":"available"},"bytes_base64":{"description":"Present for a file up to 10 MB.","type":"string"},"download_url":{"description":"The file itself: GET it with no header. It is its own credential, works until expires_at, and only while the chat stays open.","type":"string"},"expires_at":{"description":"When download_url stops working, ISO 8601, UTC. Call get_media again for a new one.","type":"string"}},"required":["ref","state","kind","mime","size_bytes","status_url","content_url","view_url","acquire_url","status"],"additionalProperties":false},{"type":"object","properties":{"ref":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string"},"mime":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"type":"number"},"status_url":{"type":"string"},"content_url":{"type":["string","null"]},"view_url":{"type":["string","null"]},"acquire_url":{"type":"string"},"status":{"type":"string","enum":["pending","gone","too_large","failed"]}},"required":["ref","state","kind","mime","status_url","content_url","view_url","acquire_url","status"],"additionalProperties":false}]},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/recipients":{"get":{"operationId":"find_recipient","tags":["Targets"],"description":"Find who to send to by phone number (with its country code) or saved contact name, including someone with no chat yet. A chat already open answers as that chat. Someone new answers with new_chat true and the same send action as chat_detail; the chat the send starts stays open for sending. Starting a chat is allowed only when the person's number has default access read and send, with personal chats on. A partial contact name is refused with candidates, never completed.","parameters":[{"name":"to","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"A phone number with its country code (+972501234567), or a saved contact's exact name."},"description":"A phone number with its country code (+972501234567), or a saved contact's exact name."},{"name":"from","in":"query","required":false,"schema":{"description":"Which of the person's numbers sends, by its name in Circles. Needed only when more than one could.","type":"string","minLength":1,"maxLength":200},"description":"Which of the person's numbers sends, by its name in Circles. Needed only when more than one could."}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"name":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"level":{"type":"string","enum":["read","send"]},"archived":{"type":"boolean"},"connection_state":{"type":"string"},"details_url":{"type":"string"},"name_provenance":{"type":"string","const":"unverified_display_name"},"target_version":{"type":"string"},"capabilities":{"type":"object","properties":{"send":{"type":"boolean"},"reply":{"type":"boolean"},"react":{"type":"boolean"},"poll_vote":{"type":"boolean","const":false}},"required":["send","reply","react","poll_vote"],"additionalProperties":false},"capability_reasons":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}},"capability_notes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"For each refused action: why, and what IS allowed instead (for example, when the daily limit resets)."},"confirmation":{"type":"object","properties":{"requested":{"type":"boolean"},"meaning":{"type":"string"}},"required":["requested","meaning"],"additionalProperties":false},"new_chat":{"type":"boolean","description":"True when there is no chat with them yet: the send starts one, which then stays open for sending."},"actions":{"type":"object","properties":{"send":{"type":"object","properties":{"submission_ref":{"type":"string"},"target_version":{"type":"string"},"expires_at":{"type":"string"},"method":{"type":"string","const":"POST","description":"Perform the action with this method..."},"url":{"type":"string","description":"...at this URL..."},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"...with these headers, and your own Authorization: Bearer header added..."},"body":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"...and this JSON body, replacing the <placeholder> with the text or emoji. Everything else is already filled in."},"optional_body":{"description":"Fields the body may also carry, with their exact shape. A send may carry a file this way.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["submission_ref","target_version","expires_at","method","url","headers","body"],"additionalProperties":false,"description":"A complete request for one action. Copy it; a submission is executed at most once and never retried."}},"additionalProperties":false}},"required":["chat_ref","name","account","kind","level","connection_state","details_url","name_provenance","target_version","capabilities","capability_reasons","capability_notes","confirmation","new_chat","actions"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/chats/{chat_ref}":{"get":{"operationId":"chat_detail","tags":["Targets"],"description":"Review the exact currently authorized recipient and obtain a server-issued submission challenge. A person visible only as a group member is not a DM destination.","parameters":[{"name":"chat_ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"name":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"level":{"type":"string","enum":["read","send"]},"archived":{"type":"boolean"},"connection_state":{"type":"string"},"details_url":{"type":"string"},"name_provenance":{"type":"string","const":"unverified_display_name"},"target_version":{"type":"string"},"capabilities":{"type":"object","properties":{"send":{"type":"boolean"},"reply":{"type":"boolean"},"react":{"type":"boolean"},"poll_vote":{"type":"boolean","const":false}},"required":["send","reply","react","poll_vote"],"additionalProperties":false},"capability_reasons":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}},"capability_notes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"For each refused action: why, and what IS allowed instead (for example, when the daily limit resets)."},"confirmation":{"type":"object","properties":{"requested":{"type":"boolean"},"meaning":{"type":"string"}},"required":["requested","meaning"],"additionalProperties":false},"new_chat":{"type":"boolean","description":"True when there is no chat with them yet: the send starts one, which then stays open for sending."},"actions":{"type":"object","properties":{"send":{"type":"object","properties":{"submission_ref":{"type":"string"},"target_version":{"type":"string"},"expires_at":{"type":"string"},"method":{"type":"string","const":"POST","description":"Perform the action with this method..."},"url":{"type":"string","description":"...at this URL..."},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"...with these headers, and your own Authorization: Bearer header added..."},"body":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"...and this JSON body, replacing the <placeholder> with the text or emoji. Everything else is already filled in."},"optional_body":{"description":"Fields the body may also carry, with their exact shape. A send may carry a file this way.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["submission_ref","target_version","expires_at","method","url","headers","body"],"additionalProperties":false,"description":"A complete request for one action. Copy it; a submission is executed at most once and never retried."}},"additionalProperties":false}},"required":["chat_ref","name","account","kind","level","connection_state","details_url","name_provenance","target_version","capabilities","capability_reasons","capability_notes","confirmation","new_chat","actions"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/messages/{message_ref}":{"get":{"operationId":"message_detail","tags":["Targets"],"description":"Review one authorized stored message. Read permission is required even for send-only clients. Reply and reaction actions exist only when transport and stored-key prerequisites are met.","parameters":[{"name":"message_ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."}}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"name":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"level":{"type":"string","enum":["read","send"]},"archived":{"type":"boolean"},"connection_state":{"type":"string"},"details_url":{"type":"string"},"name_provenance":{"type":"string","const":"unverified_display_name"},"target_version":{"type":"string"},"capabilities":{"type":"object","properties":{"send":{"type":"boolean"},"reply":{"type":"boolean"},"react":{"type":"boolean"},"poll_vote":{"type":"boolean","const":false}},"required":["send","reply","react","poll_vote"],"additionalProperties":false},"capability_reasons":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}},"capability_notes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"For each refused action: why, and what IS allowed instead (for example, when the daily limit resets)."},"confirmation":{"type":"object","properties":{"requested":{"type":"boolean"},"meaning":{"type":"string"}},"required":["requested","meaning"],"additionalProperties":false},"chat":{"type":"object","properties":{"chat_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."},"name":{"type":"string"},"account":{"type":"string"},"kind":{"type":"string"},"level":{"type":"string","enum":["read","send"]},"archived":{"type":"boolean"},"connection_state":{"type":"string"},"details_url":{"type":"string"},"name_provenance":{"type":"string","const":"unverified_display_name"}},"required":["chat_ref","name","account","kind","level","connection_state","details_url","name_provenance"],"additionalProperties":false},"message_ref":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."},"at":{"type":"string"},"from_me":{"type":"boolean"},"sender":{"type":"string"},"text":{"type":"string"},"text_truncated":{"type":"boolean"},"actions":{"type":"object","properties":{"reply":{"type":"object","properties":{"submission_ref":{"type":"string"},"target_version":{"type":"string"},"expires_at":{"type":"string"},"method":{"type":"string","const":"POST","description":"Perform the action with this method..."},"url":{"type":"string","description":"...at this URL..."},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"...with these headers, and your own Authorization: Bearer header added..."},"body":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"...and this JSON body, replacing the <placeholder> with the text or emoji. Everything else is already filled in."},"optional_body":{"description":"Fields the body may also carry, with their exact shape. A send may carry a file this way.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["submission_ref","target_version","expires_at","method","url","headers","body"],"additionalProperties":false,"description":"A complete request for one action. Copy it; a submission is executed at most once and never retried."},"react":{"type":"object","properties":{"submission_ref":{"type":"string"},"target_version":{"type":"string"},"expires_at":{"type":"string"},"method":{"type":"string","const":"POST","description":"Perform the action with this method..."},"url":{"type":"string","description":"...at this URL..."},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"...with these headers, and your own Authorization: Bearer header added..."},"body":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"...and this JSON body, replacing the <placeholder> with the text or emoji. Everything else is already filled in."},"optional_body":{"description":"Fields the body may also carry, with their exact shape. A send may carry a file this way.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["submission_ref","target_version","expires_at","method","url","headers","body"],"additionalProperties":false,"description":"A complete request for one action. Copy it; a submission is executed at most once and never retried."}},"additionalProperties":false},"reactions":{"description":"Everyone's current reaction on this message, one per person, oldest first.","type":"array","items":{"type":"object","properties":{"emoji":{"type":"string","description":"One emoji."},"from":{"type":"string","description":"Who reacted, by the name a sender is shown with; you for this number."},"fromMe":{"type":"boolean"},"at":{"type":"number","description":"When it was set: milliseconds since 1970-01-01, UTC."},"at_iso":{"type":"string","description":"The same moment in ISO 8601, UTC (ends in Z)."}},"required":["emoji","from","fromMe","at","at_iso"],"additionalProperties":false}},"my_reaction":{"description":"This number's reaction on this message, set on the phone or through Circles, or null. status is on_whatsapp when WhatsApp reported it.","anyOf":[{"type":"object","properties":{"emoji":{"type":"string"},"status":{"type":"string"},"set_at":{"type":"string"}},"required":["emoji","status","set_at"],"additionalProperties":false},{"type":"null"}]},"reaction_semantics":{"type":"string"}},"required":["chat_ref","name","account","kind","level","connection_state","details_url","name_provenance","target_version","capabilities","capability_reasons","capability_notes","confirmation","chat","message_ref","at","from_me","sender","text","text_truncated","actions","reaction_semantics"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/chats/{chat_ref}/messages":{"post":{"operationId":"send","tags":["Writes"],"description":"Send one message to a chat the person explicitly opened for sending: text, a file of any type (a PDF, a document, a photo, a video), or a file with the text as its caption. Someone with no chat yet can be messaged too, when the person's number has default access read and send: give their phone number with its country code (+972501234567), or their saved contact name exactly; the chat that starts stays open for sending. Rare by design, capped per day, and never retried. `confirmed` asserts the person just agreed to this exact text going to this exact chat; the service cannot verify that and does not treat it as permission. The HTTP API uses this single exact-target route. The submission_ref and target_version must come from the recipient preview. No automatic retries. To send an image, include `image` (JPEG, PNG or WebP, base64, up to about 3 MB); `text` is then its caption and optional.","parameters":[{"name":"chat_ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque chat reference returned by an authorized read; never a chat name or provider ID."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_ref":{"type":"string","minLength":1,"maxLength":4096,"description":"Server-issued, target-bound submission reference from the latest detail preview. Reusing it never sends twice."},"target_version":{"type":"string","minLength":1,"maxLength":4096,"description":"Exact target version from the detail preview; stale previews are refused."},"confirmed":{"type":"boolean","const":true,"description":"Caller assertion that the person agreed to this exact action and target. This does not prove human approval."},"text":{"description":"The message, up to 65,536 characters (WhatsApp's own limit). With a file, its caption, up to 4,096, and then optional.","type":"string","maxLength":65536},"file":{"description":"One file of any type to send, with `text` as its caption.","type":"object","properties":{"mime":{"type":"string","minLength":3,"maxLength":255,"description":"The file's type, e.g. application/pdf, image/jpeg, video/mp4."},"data_base64":{"type":"string","minLength":1,"maxLength":4000000,"description":"The file, base64-encoded (standard alphabet, padded). Up to about 3 MB of file."},"filename":{"description":"The name the chat shows, e.g. nda.pdf. A document without one is named for its type.","type":"string","minLength":1,"maxLength":255}},"required":["mime","data_base64"],"additionalProperties":false},"image":{"description":"The older name for a file that is a photo (JPEG, PNG or WebP). Use `file`.","type":"object","properties":{"mime":{"type":"string","enum":["image/jpeg","image/png","image/webp"],"description":"The image's type."},"data_base64":{"type":"string","minLength":1,"maxLength":4000000,"description":"The image file, base64-encoded (standard alphabet, padded). Up to about 3 MB of image."},"filename":{"description":"A file name to show with the image.","type":"string","minLength":1,"maxLength":255}},"required":["mime","data_base64"],"additionalProperties":false}},"required":["submission_ref","target_version","confirmed"],"additionalProperties":false}}}},"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"202":{"description":"The submission is pending. Navigate Location for its receipt; never retry delivery automatically.","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/messages/{message_ref}/replies":{"post":{"operationId":"reply","tags":["Writes"],"description":"Capability-gated native quoted reply. The exact original provider key and authorized stored quote must be available. No unquoted fallback and no automatic retries.","parameters":[{"name":"message_ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_ref":{"type":"string","minLength":1,"maxLength":4096,"description":"Server-issued, target-bound submission reference from the latest detail preview. Reusing it never sends twice."},"target_version":{"type":"string","minLength":1,"maxLength":4096,"description":"Exact target version from the detail preview; stale previews are refused."},"confirmed":{"type":"boolean","const":true,"description":"Caller assertion that the person agreed to this exact action and target. This does not prove human approval."},"text":{"type":"string","minLength":1,"maxLength":65536,"description":"The reply, up to 65,536 characters (WhatsApp's own limit)."}},"required":["submission_ref","target_version","confirmed","text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"202":{"description":"The submission is pending. Navigate Location for its receipt; never retry delivery automatically.","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/messages/{message_ref}/reactions":{"post":{"operationId":"react","tags":["Writes"],"description":"Capability-gated reaction to the exact original provider key. Replaces this account's prior reaction. Poll voting and reaction removal are unsupported.","parameters":[{"name":"message_ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque message reference returned by an authorized read."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_ref":{"type":"string","minLength":1,"maxLength":4096,"description":"Server-issued, target-bound submission reference from the latest detail preview. Reusing it never sends twice."},"target_version":{"type":"string","minLength":1,"maxLength":4096,"description":"Exact target version from the detail preview; stale previews are refused."},"confirmed":{"type":"boolean","const":true,"description":"Caller assertion that the person agreed to this exact action and target. This does not prove human approval."},"emoji":{"type":"string","minLength":1,"maxLength":64,"description":"One emoji sequence. Replaces this account's prior reaction; an empty string never removes a reaction."}},"required":["submission_ref","target_version","confirmed","emoji"],"additionalProperties":false}}}},"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"202":{"description":"The submission is pending. Navigate Location for its receipt; never retry delivery automatically.","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/writes/{submission_ref}":{"get":{"operationId":"write_receipt","tags":["Targets"],"description":"Read an authorized submission's receipt without retrying delivery. Unknown provider outcomes must not be retried automatically.","parameters":[{"name":"submission_ref","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"202":{"description":"The existing submission is still pending. This GET never repeats delivery.","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","enum":["accepted","pending","delivery_unknown","refused"]},"operation":{"type":"string","enum":["send","reply","react"]},"submission_ref":{"type":"string"},"receipt_url":{"type":"string"},"retryable":{"type":"boolean","const":false},"message":{"type":"string"},"reason":{"type":"string"}},"required":["status","operation","submission_ref","receipt_url","retryable","message"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/connect/exchange":{"post":{"operationId":"connect_exchange","tags":["Connect"],"security":[],"description":"Exchange the one-time code from the person's WhatsApp message for your key. Send no Authorization header: the code is the credential. A code works once, for one hour, and gives no access until it is exchanged. Save the key at once in your secrets; it is shown only in this answer. A spent, expired, unknown or disconnected code is refused with the same 400, which names what to do: ask the person to connect you again from the Agents page.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":120,"description":"The one-time code from the message, starting circ_code_."}},"required":["code"],"additionalProperties":false}}}},"responses":{"200":{"description":"Your key, once. Send it on every other request as `Authorization: Bearer <key>`.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"key":{"type":"string","description":"Your key: circ_ and then letters, digits, - and _."},"key_prefix":{"type":"string","description":"Its first characters, as the person's Agents page shows them."},"expires_at":{"description":"When it stops working (ISO 8601, UTC); null for no limit.","type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"how_to_use":{"type":"string","const":"Authorization: Bearer <key>"},"save_it":{"type":"string"},"start_url":{"type":"string","description":"The first read to make with the key."},"openapi_url":{"type":"string"}},"required":["key","key_prefix","expires_at","scopes","how_to_use","save_it","start_url","openapi_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"Not exactly {\"code\": \"<string>\"} as JSON (invalid_input, naming the shape), or a code that does not connect anything (invalid_code, the same answer whatever the reason).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"405":{"description":"Use POST.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The body is larger than a code needs (1 KB).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"415":{"description":"The body must be sent as Content-Type: application/json.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Too many tries from this address. Wait before trying again.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted try.","schema":{"type":"integer"}}}}}}},"/api/v1/agent/media/{ref}/status":{"get":{"operationId":"media_status","tags":["Media"],"description":"Read current attachment state without initiating acquisition.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Authorized result. Reads return complete next_url links; refresh page one for new arrivals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"ref":{"type":"string"},"state":{"type":"string","enum":["available","downloading","on_request","gone","too_large","failed"]},"kind":{"type":"string"},"mime":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"type":"number"},"status_url":{"type":"string"},"content_url":{"type":["string","null"]},"view_url":{"type":["string","null"]},"acquire_url":{"type":"string"}},"required":["ref","state","kind","mime","status_url","content_url","view_url","acquire_url"],"additionalProperties":false},"notices":{"type":"array","items":{"type":"string"}}},"required":["ok","data"],"additionalProperties":{}}}}},"400":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"413":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"422":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"429":{"description":"Rate or daily send cap reached. For a cap refusal, data retains the non-retriable write receipt and error.reset_at gives the UTC reset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}},"headers":{"Retry-After":{"description":"Seconds until the next permitted request.","schema":{"type":"integer"}}}},"502":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"503":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/media/{ref}/content":{"get":{"operationId":"media_content","tags":["Media"],"description":"Download an already available attachment with current authorization; active content is forced to download.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Authorized attachment bytes.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}},"/api/v1/agent/media/{ref}/view":{"get":{"operationId":"media_view","tags":["Media"],"description":"Show an already available PDF, image, audio or video inline in the browser (its view_url). Anything else, HTML and SVG included, is the same sandboxed download as content and never renders.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Authorized attachment bytes.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"audio/*":{"schema":{"type":"string","format":"binary"}},"video/*":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"403":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"404":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}},"409":{"description":"The action was refused. Inspect error.code; error.message says what is missing and what IS allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["ok","error"],"additionalProperties":{}}}}}}}}},"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","description":"A key from the person's Agents page (New token, then API with a key), sent as `Authorization: Bearer <key>` on every request. Scoped MCP bearer grants also work. Nothing else is accepted: not a browser session or cookie (browser agents were removed on 2026-10-27)."}}}}