{"openapi":"3.1.0","info":{"title":"RCS Campaigns agent gateway","version":"p0","summary":"Authenticated HTTP gateway for autonomous agents.","description":"Discover, author, clone, render, approve, and send RCS message templates and conversational surveys programmatically. Generated from the gateway's own tool catalog, so request arguments are the schemas it actually validates against. Response bodies are described loosely — the catalog types inputs but not outputs. The same catalog is exposed as an MCP server and a CLI.","contact":{"name":"RCS Campaigns","url":"https://www.rcs-campaigns.com"}},"servers":[{"url":"https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com/api/agent","description":"Hosted production gateway."}],"tags":[{"name":"Discovery"},{"name":"Templates"},{"name":"Surveys"},{"name":"Knowledge"},{"name":"Account"},{"name":"Audiences"},{"name":"Inbox"},{"name":"Webhooks"},{"name":"Contacts"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"A scoped agent key, minted by an org admin. Shown once, stored only as a SHA-256 hash, and revocable. Separate rail from the human app: the master key is not accepted here."}}},"security":[{"agentKey":[]}],"x-scopes":{"templates:read":"Search, fetch, and render templates, and read grounding docs","templates:write":"Author, revise, duplicate, and delete drafts, and manage grounding","templates:submit":"Submit drafts for provider approval","marketplace:clone":"Clone marketplace templates and surveys into your org","messages:send":"Broadcast templates to recipients","surveys:read":"Search, fetch, render, and list sends for surveys","surveys:write":"Author, patch, and delete surveys, and upload media","surveys:submit":"Submit surveys for provider approval","surveys:send":"Send survey tests and live survey runs","results:read":"Read survey responses","audiences:read":"List audiences and their contacts","audiences:write":"Create and delete audiences, and import contacts","contacts:read":"Search and read the org-level contact record","contacts:write":"Correct names, email, merge fields and tags — never consent","conversations:read":"List threads, and read a thread with its messages","conversations:write":"Reply into a thread, and assign or release it","webhooks:manage":"Register, update, delete, and test outbound webhook endpoints","usage:read":"Read metered usage for the org"},"paths":{"/capabilities":{"get":{"operationId":"capabilities","summary":"Catalog + granted scopes","description":"Machine-readable map of the gateway: every tool with its method, path, and required scope, the scopes your key actually holds, and the pricing seam (null today). Call it first to plan what you may do.","tags":["Discovery"],"security":[{"agentKey":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key revoked."},"429":{"description":"Rate limited."}}}},"/templates":{"get":{"operationId":"search_templates","summary":"Search the library","description":"Discover templates by query, channel, and category. Sort by rating or by most-cloned.","tags":["Templates"],"security":[{"agentKey":["templates:read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search over name + description.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"MarketplaceCategory key, e.g. EVENTS.","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["RCS","WHATSAPP","SMS"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["rating","used"],"default":"rating"}},{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:read scope."},"429":{"description":"Rate limited."}}},"post":{"operationId":"create_template","summary":"Create a draft","description":"Author a new template from a content object. The shared validator rejects anything that breaks channel rules with machine-coded errors.","tags":["Templates"],"security":[{"agentKey":["templates:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"channel":{"type":"string","enum":["RCS","WHATSAPP","SMS"]},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"content":{"type":"object","description":"TemplateContent. Must include a non-empty smsFallback. One of text/card/carousel is the primary body."},"tags":{"type":"array","items":{"type":"string"}}},"required":["name","content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}":{"get":{"operationId":"get_template","summary":"Fetch one template","description":"Fetch one template — content, channel, ratings, clone count, and (where shared) its grounding knowledge doc.","tags":["Templates"],"security":[{"agentKey":["templates:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:read scope."},"429":{"description":"Rate limited."}}},"put":{"operationId":"update_template","summary":"Update a draft","description":"Revise a draft in place, re-running the same validator that gates creation.","tags":["Templates"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"channel":{"type":"string","enum":["RCS","WHATSAPP"],"description":"Move the template to another channel. Requires the matching add-on brand; omit to leave it where it is."},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"content":{"type":"object","description":"Full replacement TemplateContent (not a deep merge). Must include a non-empty smsFallback."},"tags":{"type":"array","items":{"type":"string"}},"knowledgeDoc":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}},"delete":{"operationId":"delete_template","summary":"Delete a template","description":"Remove a template you own from the org.","tags":["Templates"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}/render":{"post":{"operationId":"render_template","summary":"Render + validate","description":"Try before you send: render with sample variables and inspect the validated RCS payload plus the mandatory SMS fallback.","tags":["Templates"],"security":[{"agentKey":["templates:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"object","description":"Merge fields ({{key}} -> value) to bind into the preview.","additionalProperties":{"type":"string"}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:read scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}/duplicate":{"post":{"operationId":"duplicate_template","summary":"Fork your own template","description":"Fork one of your own templates into a fresh draft — the in-org counterpart to cloning from the marketplace.","tags":["Templates"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}}},"/marketplace/{id}/clone":{"post":{"operationId":"clone_template","summary":"Clone into your org","description":"Deep-copy a marketplace listing into your org as a clean private draft you fully own — no provenance carried over.","tags":["Templates"],"security":[{"agentKey":["marketplace:clone"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the marketplace:clone scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}/submit":{"post":{"operationId":"submit_template","summary":"Submit for approval","description":"Send a draft to the provider for brand approval and read back its approval status. Until it is approved, sends fall back to SMS.","tags":["Templates"],"security":[{"agentKey":["templates:submit"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:submit scope."},"429":{"description":"Rate limited."}}}},"/messages/send":{"post":{"operationId":"send_message","summary":"Broadcast to recipients","description":"Broadcast an org-owned template to an E.164 list — RCS-first, with the always-on SMS/MMS fallback. Returns the delivery funnel, including how many recipients fell back.","tags":["Templates"],"security":[{"agentKey":["messages:send"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blueprintId":{"type":"string"},"to":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500},"variables":{"type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string"}},"required":["blueprintId","to"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the messages:send scope."},"429":{"description":"Rate limited."}}}},"/surveys":{"get":{"operationId":"search_surveys","summary":"Search surveys","description":"Find conversational surveys by query across the library and your org.","tags":["Surveys"],"security":[{"agentKey":["surveys:read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search over the name.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["DRAFT","SCHEDULED","ACTIVE","CLOSED"]}},{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:read scope."},"429":{"description":"Rate limited."}}},"post":{"operationId":"create_survey","summary":"Create a survey","description":"Author a new conversational survey from a question set.","tags":["Surveys"],"security":[{"agentKey":["surveys:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"definition":{"type":"object","description":"SurveyDefinition: { intro?, outro?, questions: [{ questionId, prompt, type, options?, minRating?, maxRating?, required? }] }."},"startDate":{"type":"string","description":"ISO date; schedules the survey."},"endDate":{"type":"string"},"timezone":{"type":"string"},"languageCode":{"type":"array","items":{"type":"string"}},"isPreferencesSurvey":{"type":"boolean"},"channel":{"type":"string","enum":["RCS","WHATSAPP"],"description":"Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand."}},"required":["name","definition"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:write scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}":{"get":{"operationId":"get_survey","summary":"Fetch one survey","description":"Fetch one survey — its questions, branching, and current approval state.","tags":["Surveys"],"security":[{"agentKey":["surveys:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:read scope."},"429":{"description":"Rate limited."}}},"delete":{"operationId":"delete_survey","summary":"Delete a survey","description":"Remove a survey you own from the org.","tags":["Surveys"],"security":[{"agentKey":["surveys:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:write scope."},"429":{"description":"Rate limited."}}},"patch":{"operationId":"update_survey","summary":"Patch a survey","description":"Patch a survey's questions, branching, or metadata.","tags":["Surveys"],"security":[{"agentKey":["surveys:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"definition":{"type":"object"},"status":{"type":"string","enum":["DRAFT","SCHEDULED","ACTIVE","CLOSED"]},"startDate":{"type":"string"},"endDate":{"type":"string"},"audienceIds":{"type":"array","items":{"type":"string"}},"channel":{"type":"string","enum":["RCS","WHATSAPP"],"description":"Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:write scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/render":{"post":{"operationId":"render_survey","summary":"Preview the conversation","description":"Preview the whole conversation as the recipient will walk it, before anything is sent.","tags":["Surveys"],"security":[{"agentKey":["surveys:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:read scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/clone":{"post":{"operationId":"clone_survey","summary":"Clone into your org","description":"Copy a published survey into your org as a private draft.","tags":["Surveys"],"security":[{"agentKey":["marketplace:clone"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the marketplace:clone scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/submit":{"post":{"operationId":"submit_survey","summary":"Submit for approval","description":"Send a survey for provider approval — the same gate templates pass through.","tags":["Surveys"],"security":[{"agentKey":["surveys:submit"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["RCS","WHATSAPP"],"description":"Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:submit scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/send":{"post":{"operationId":"send_survey","summary":"Run against an audience","description":"Run the survey against an audience. Billable and irreversible — rehearse with send_survey_test first.","tags":["Surveys"],"security":[{"agentKey":["surveys:send"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"maxItems":500,"description":"E.164 destinations, e.g. [\"+15551234567\"]."},"audienceIds":{"type":"array","items":{"type":"string"},"maxItems":100},"channel":{"type":"string","enum":["RCS","WHATSAPP"],"description":"Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:send scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/sends":{"get":{"operationId":"list_survey_sends","summary":"Send history","description":"Read the send history for one survey — who it went to and when.","tags":["Surveys"],"security":[{"agentKey":["surveys:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:read scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/send-test":{"post":{"operationId":"send_survey_test","summary":"Send yourself a test","description":"Send the survey to yourself first. The rehearsal that keeps a broken branch from reaching an audience.","tags":["Surveys"],"security":[{"agentKey":["surveys:send"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"E.164, e.g. +15551234567."},"channel":{"type":"string","enum":["RCS","WHATSAPP"],"description":"Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand."}},"required":["number"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:send scope."},"429":{"description":"Rate limited."}}}},"/surveys/{id}/results":{"get":{"operationId":"get_results","summary":"Read responses","description":"Pull the answers back as structured data, so the agent that ran the survey can act on what it learned.","tags":["Surveys"],"security":[{"agentKey":["results:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the results:read scope."},"429":{"description":"Rate limited."}}}},"/media/upload":{"post":{"operationId":"upload_media","summary":"Host card media","description":"Host an image or video for use as rich-card media.","tags":["Surveys"],"security":[{"agentKey":["surveys:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"base64":{"type":"string","description":"Raw base64 or data: URL of the image bytes."},"mime":{"type":"string","description":"Image MIME type (required with base64), e.g. image/png."},"filename":{"type":"string"},"sourceUrl":{"type":"string","description":"https image URL to fetch and re-host onto GCS."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the surveys:write scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}/knowledge":{"get":{"operationId":"get_knowledge","summary":"Read the grounding doc","description":"Read a template's grounding doc — the source of truth a reply bot answers from.","tags":["Knowledge"],"security":[{"agentKey":["templates:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:read scope."},"429":{"description":"Rate limited."}}},"put":{"operationId":"set_knowledge","summary":"Set the grounding doc","description":"Attach or replace the grounding doc behind a template.","tags":["Knowledge"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"doc":{"type":"string","description":"The knowledge document (markdown or plain text)."}},"required":["doc"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}},"delete":{"operationId":"delete_knowledge","summary":"Delete the grounding doc","description":"Remove a template's grounding doc entirely.","tags":["Knowledge"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}/knowledge/enable":{"post":{"operationId":"enable_knowledge","summary":"Turn grounding on","description":"Switch grounding on for a template without deleting or re-uploading the doc.","tags":["Knowledge"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}}},"/templates/{id}/knowledge/disable":{"post":{"operationId":"disable_knowledge","summary":"Turn grounding off","description":"Switch grounding off while keeping the doc in place.","tags":["Knowledge"],"security":[{"agentKey":["templates:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the templates:write scope."},"429":{"description":"Rate limited."}}}},"/usage":{"get":{"operationId":"get_usage","summary":"Read metered usage","description":"Read the org's month-to-date metered usage — the same ledger the human dashboard and billing meter count.","tags":["Account"],"security":[{"agentKey":["usage:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the usage:read scope."},"429":{"description":"Rate limited."}}}},"/audiences":{"get":{"operationId":"search_audiences","summary":"List audiences","description":"List and filter the org's contact lists.","tags":["Audiences"],"security":[{"agentKey":["audiences:read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search over the name.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the audiences:read scope."},"429":{"description":"Rate limited."}}},"post":{"operationId":"create_audience","summary":"Create an audience","description":"Create a new contact list for an agent to send against.","tags":["Audiences"],"security":[{"agentKey":["audiences:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","description":"Free-text provenance, e.g. \"Jaipur wedding planners leads.csv\"."},"contacts":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"number":{"type":"string","description":"Phone number; required for the contact to be reachable."},"email":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false}}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the audiences:write scope."},"429":{"description":"Rate limited."}}}},"/audiences/{id}":{"get":{"operationId":"get_audience","summary":"Fetch one audience","description":"Fetch one audience and its size.","tags":["Audiences"],"security":[{"agentKey":["audiences:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the audiences:read scope."},"429":{"description":"Rate limited."}}},"delete":{"operationId":"delete_audience","summary":"Delete an audience","description":"Remove an audience from the org.","tags":["Audiences"],"security":[{"agentKey":["audiences:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the audiences:write scope."},"429":{"description":"Rate limited."}}}},"/audiences/{id}/contacts":{"get":{"operationId":"list_audience_contacts","summary":"Page through contacts","description":"Page through the contacts inside an audience.","tags":["Audiences"],"security":[{"agentKey":["audiences:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Free-text over number, names and email. A number matches however it is written — \"(206) 300-0001\" finds \"+12063000001\".","schema":{"type":"string","maxLength":120}},{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the audiences:read scope."},"429":{"description":"Rate limited."}}},"post":{"operationId":"import_contacts","summary":"Import contacts","description":"Bulk-add E.164 contacts to an audience — the step that turns a spreadsheet into a sendable list.","tags":["Audiences"],"security":[{"agentKey":["audiences:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"number":{"type":"string"},"email":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false},"minItems":1}},"required":["contacts"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the audiences:write scope."},"429":{"description":"Rate limited."}}}},"/conversations":{"get":{"operationId":"list_conversations","summary":"List threads","description":"The org's conversation threads, one per phone number, newest activity first. Archived threads are hidden. Filter by free text, unread, unassigned, a named assignee, or the campaign a thread was messaged in.","tags":["Inbox"],"security":[{"agentKey":["conversations:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Match the number or the resolved display name.","schema":{"type":"string"}},{"name":"unread","in":"query","required":false,"description":"Only threads with unanswered arrivals (unreadCount > 0). Org-wide, not per-viewer: a key is not a person and has no read state.","schema":{"type":"boolean"}},{"name":"unassigned","in":"query","required":false,"description":"Only threads nobody owns.","schema":{"type":"boolean"}},{"name":"assignedTo","in":"query","required":false,"description":"Only threads owned by this Clerk user id.","schema":{"type":"string"}},{"name":"broadcastId","in":"query","required":false,"description":"Only threads this campaign was sent to.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the conversations:read scope."},"429":{"description":"Rate limited."}}}},"/conversations/{id}":{"get":{"operationId":"get_conversation","summary":"Read one thread","description":"One thread in a single call: its meta, the most recent messages oldest-first, the contact summary (marketing status, tags, audiences), and — for WhatsApp threads — whether the 24-hour service window is still open. Internal team notes are deliberately excluded.","tags":["Inbox"],"security":[{"agentKey":["conversations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many of the most recent messages to include.","schema":{"type":"number","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the conversations:read scope."},"429":{"description":"Rate limited."}}}},"/conversations/{id}/reply":{"post":{"operationId":"reply","summary":"Reply into a thread","description":"Send free text (optionally with an image) or an approved template into a thread. This reaches a real phone and bills your org. Every gate a human operator hits applies unchanged: an opted-out number is refused, the allowance is enforced, an RCS send always carries its SMS fallback, and WhatsApp free text needs the 24-hour window open (an approved template otherwise). Where the thread has an outbound language set, free text is translated into it first, exactly as the composer does.","tags":["Inbox"],"security":[{"agentKey":["conversations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["text","template"]},"text":{"type":"string","maxLength":4096,"description":"kind=text: the body. May be empty when mediaUrl carries the message."},"mediaUrl":{"type":"string","description":"kind=text: a public https image URL to attach."},"blueprintId":{"type":"string","description":"kind=template: the org template to send."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"kind=template: values for the template's {{variables}}."}},"required":["kind"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the conversations:write scope."},"429":{"description":"Rate limited."}}}},"/conversations/{id}/assign":{"post":{"operationId":"assign_conversation","summary":"Assign or release","description":"Give a thread an owner, or release it back to the pool by passing a null user id. The assignee is a bare user id and is not checked against the org roster, so a stale id degrades visibly to “assigned to someone who left” rather than failing the write.","tags":["Inbox"],"security":[{"agentKey":["conversations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":["string","null"],"description":"Clerk user id to hand the thread to; null releases it."}},"required":["userId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the conversations:write scope."},"429":{"description":"Rate limited."}}}},"/webhooks":{"get":{"operationId":"list_webhooks","summary":"List endpoints","description":"The org's registered outbound webhook endpoints. The signing secret is redacted — it is shown only once, when the endpoint is created.","tags":["Webhooks"],"security":[{"agentKey":["webhooks:manage"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the webhooks:manage scope."},"429":{"description":"Rate limited."}}},"post":{"operationId":"create_webhook","summary":"Register an endpoint","description":"Register an HTTPS endpoint to receive signed platform events. The response carries the signing secret exactly once — store it then, because every later read redacts it and there is no way to retrieve it again.","tags":["Webhooks"],"security":[{"agentKey":["webhooks:manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint to POST events to."},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["survey.completed","response.received","message.received","message.delivered","message.failed","broadcast.completed","contact.opted_out","action.tapped","flow.started","flow.completed","payment.completed","payment.failed","contact.lead_captured"]},"description":"Event types to subscribe to."},"description":{"type":"string","maxLength":200}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the webhooks:manage scope."},"429":{"description":"Rate limited."}}}},"/webhooks/{id}":{"put":{"operationId":"update_webhook","summary":"Update an endpoint","description":"Change an endpoint's url, subscribed events, description, or active flag. Only the fields you pass change, and the signing secret is neither returned nor rotated here.","tags":["Webhooks"],"security":[{"agentKey":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["survey.completed","response.received","message.received","message.delivered","message.failed","broadcast.completed","contact.opted_out","action.tapped","flow.started","flow.completed","payment.completed","payment.failed","contact.lead_captured"]}},"description":{"type":["string","null"],"maxLength":200},"active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the webhooks:manage scope."},"429":{"description":"Rate limited."}}},"delete":{"operationId":"delete_webhook","summary":"Remove an endpoint","description":"Remove a webhook endpoint. Its delivery history goes with it, and anything still queued for it stops.","tags":["Webhooks"],"security":[{"agentKey":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the webhooks:manage scope."},"429":{"description":"Rate limited."}}}},"/webhooks/{id}/test":{"post":{"operationId":"test_webhook","summary":"Fire a test event","description":"Fire a synthetic signed event at one endpoint to verify the receiver. Returns the delivery id and whether it was accepted.","tags":["Webhooks"],"security":[{"agentKey":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the webhooks:manage scope."},"429":{"description":"Rate limited."}}}},"/contacts":{"get":{"operationId":"list_contacts","summary":"Search contacts","description":"Search the org's contact records — one person per number, across every audience. Returns consent, opt-out, the number verdict, marketing status, merge fields and tags.","tags":["Contacts"],"security":[{"agentKey":["contacts:read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text over number, names and email.","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","required":false,"description":"Marketing status: SUBSCRIBED (consent, not opted out), UNSUBSCRIBED (opted out — sticky), UNDELIVERABLE (number known unreachable), UNKNOWN (no consent on record).","schema":{"type":"string","enum":["SUBSCRIBED","UNSUBSCRIBED","UNDELIVERABLE","UNKNOWN"]}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","maxLength":64}},{"name":"audienceId","in":"query","required":false,"description":"Only people who are members of this audience.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the contacts:read scope."},"429":{"description":"Rate limited."}}}},"/contacts/{id}":{"get":{"operationId":"get_contact","summary":"Fetch one contact","description":"Fetch one contact by its public contact id, along with the audiences they belong to.","tags":["Contacts"],"security":[{"agentKey":["contacts:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the contacts:read scope."},"429":{"description":"Rate limited."}}},"patch":{"operationId":"update_contact","summary":"Correct a contact","description":"Correct a contact's names, email, merge fields (a whole-map replace) or tags. Consent and opt-out are deliberately out of reach here: recording or clearing them is compliance-sensitive and stays with a human operator.","tags":["Contacts"],"security":[{"agentKey":["contacts:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":["string","null"],"maxLength":120},"lastName":{"type":["string","null"],"maxLength":120},"email":{"type":["string","null"],"maxLength":200},"attributes":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Whole-map replace of the {{merge field}} values."},"tags":{"type":"array","items":{"type":"string"},"maxItems":50}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Arguments failed validation."},"401":{"description":"Missing or invalid agent key."},"403":{"description":"Key does not hold the contacts:write scope."},"429":{"description":"Rate limited."}}}}}}