{ "openapi": "3.0.3", "info": { "title": "Polymorfa WhatsApp API", "version": "1.0.0", "description": "Public Polymorfa REST API for sessions, messaging, media, webhooks, campaigns, templates, client tokens, QuickLinks, and bridge routing.", "contact": { "name": "Polymorfa API", "url": "https://docs.polymorfa.com" } }, "servers": [ { "url": "https://api.polymorfa.com" } ], "security": [ { "BearerAuth": [] } ], "components": { "schemas": { "WhatsAppMessageIds": { "anyOf": [ { "type": "object", "properties": { "linked_devices": { "type": "string", "minLength": 1, "maxLength": 512 }, "official_api": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "linked_devices" ], "additionalProperties": false }, { "type": "object", "properties": { "linked_devices": { "type": "string", "minLength": 1, "maxLength": 512 }, "official_api": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "official_api" ], "additionalProperties": false } ], "description": "Exact message references observed through Linked Devices, the Official API, or both. Use the Polymorfa message id for actions and replies. Unknown provider references are omitted." }, "IdentityRef": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id" ] }, "ConversationRef": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "sender": { "$ref": "#/components/schemas/IdentityRef" } }, "required": [ "id" ] }, "PollOption": { "type": "object", "properties": { "name": { "type": "string" }, "hash": { "type": "string" } }, "required": [ "name", "hash" ] }, "MessagePayload": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/ConversationRef" }, "fromMe": { "type": "boolean" }, "timestamp": { "type": "number" }, "pushName": { "type": "string" }, "isGroup": { "type": "boolean" }, "type": { "type": "string", "enum": [ "text", "image", "video", "audio", "document", "location", "contact", "phone_number_shared", "native_flow_response", "button_reply", "list_reply", "poll", "sticker", "reaction", "revoke", "edited", "unknown" ] }, "text": { "type": "string" }, "caption": { "type": "string" }, "mimeType": { "type": "string" }, "ptt": { "type": "boolean" }, "filename": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "displayName": { "type": "string" }, "title": { "type": "string" }, "reaction": { "type": "string" }, "reactionTo": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "revokedId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "nativeFlowResponse": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "paramsJson": { "type": "string", "minLength": 1, "maxLength": 262144 }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "name", "paramsJson" ] }, "replyChoice": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "button", "list" ], "description": "Reply control the contact used: a reply or quick-reply button, or a list row." }, "id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "ID you assigned to the selected button or list row. It is never the visible label, except for a template quick-reply button sent without a payload, where WhatsApp returns the button text." } }, "required": [ "kind", "id" ], "description": "Present when the contact selects a reply button or list row." }, "parentMessageId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent." }, "media": { "type": "string" }, "mediaUrl": { "type": "string" }, "edited": { "type": "boolean" }, "pollOptions": { "type": "array", "items": { "$ref": "#/components/schemas/PollOption" } }, "unavailable": { "type": "boolean" }, "unavailableReason": { "type": "string" } }, "required": [ "id", "whatsapp_ids", "conversation", "fromMe", "timestamp", "pushName", "isGroup", "type" ] }, "CloudMessagePayload": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/ConversationRef" }, "timestamp": { "type": "string" }, "type": { "type": "string" }, "senderName": { "type": "string" }, "nativeFlowResponse": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "paramsJson": { "type": "string", "minLength": 1, "maxLength": 262144 }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "name", "paramsJson" ] }, "replyChoice": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "button", "list" ], "description": "Reply control the contact used: a reply or quick-reply button, or a list row." }, "id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "ID you assigned to the selected button or list row. It is never the visible label, except for a template quick-reply button sent without a payload, where WhatsApp returns the button text." } }, "required": [ "kind", "id" ], "description": "Present when the contact selects a reply button or list row." }, "parentMessageId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent." }, "interactive": { "type": "object", "additionalProperties": {} }, "referral": { "type": "object", "properties": { "source_type": { "type": "string" }, "source_id": { "type": "string" }, "source_url": { "type": "string" }, "ctwa_clid": { "type": "string" } }, "description": "Meta-supplied Click-to-WhatsApp entry point. Does not establish a conversion or payment." } }, "required": [ "id", "whatsapp_ids", "conversation", "timestamp", "type" ] }, "MessageReceivedPayload": { "oneOf": [ { "$ref": "#/components/schemas/MessagePayload" }, { "$ref": "#/components/schemas/CloudMessagePayload" } ] }, "MessageReceivedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.received" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageReceivedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageSentPayload": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/ConversationRef" }, "type": { "type": "string" }, "timestamp": { "type": "number" } }, "required": [ "id", "whatsapp_ids", "conversation", "type", "timestamp" ] }, "MessageSentEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.sent" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageSentPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MetaPricingReport": { "type": "object", "properties": { "billable": { "type": "boolean", "description": "Whether WhatsApp reported the message as billable. WhatsApp is deprecating this field; use `type`." }, "pricing_model": { "type": "string", "description": "WhatsApp pricing model, for example `PMP` (per-message pricing).", "example": "PMP" }, "category": { "type": "string", "description": "WhatsApp pricing category, for example `marketing`, `utility`, `authentication` or `service`.", "example": "utility" }, "type": { "type": "string", "description": "WhatsApp pricing type, for example `regular`, `free_customer_service` or `free_entry_point`.", "example": "free_customer_service" } }, "description": "Official API only. The pricing classification WhatsApp reported for this message, copied as reported. Meta bills your WhatsApp Business Account directly; this is not a Polymorfa charge and contains no price." }, "MessageAckPayload": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true } }, "required": [ "id", "whatsapp_ids" ] } }, "conversation": { "$ref": "#/components/schemas/ConversationRef" }, "from": { "$ref": "#/components/schemas/IdentityRef" }, "sender": { "$ref": "#/components/schemas/IdentityRef" }, "type": { "type": "string", "description": "Ack type: error, delivered, read, played" }, "timestamp": { "type": "number" }, "pricing": { "$ref": "#/components/schemas/MetaPricingReport" } }, "required": [ "messages", "conversation", "type", "timestamp" ] }, "MessageAckEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.ack" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageAckPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageRevokedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.revoked" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessagePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageReactionEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.reaction" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageReceivedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageEditedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.edited" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessagePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessagePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageDeletePayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "sender": { "$ref": "#/components/schemas/IdentityRef" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/ConversationRef" }, "fromMe": { "type": "boolean" } }, "required": [ "from", "sender", "id", "whatsapp_ids", "conversation", "fromMe" ] }, "MessageDeleteEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.delete" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageDeletePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "PollVotePayload": { "type": "object", "properties": { "pollMessageId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "conversation": { "$ref": "#/components/schemas/ConversationRef" }, "voter": { "$ref": "#/components/schemas/IdentityRef" }, "selectedHashes": { "type": "array", "items": { "type": "string" } }, "timestamp": { "type": "number" } }, "required": [ "pollMessageId", "conversation", "voter", "selectedHashes", "timestamp" ] }, "MessageVoteEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.vote" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/PollVotePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "RuntimeSessionStatusPayload": { "type": "object", "properties": { "status": { "type": "string", "description": "Session status: CONNECTING, CONNECTED, DISCONNECTED", "example": "DISCONNECTED" }, "statusReason": { "type": "string", "description": "Reason for the status: SCAN_QR, AUTO_RECONNECT, FAILED, MANUAL_STOP, QR_TIMEOUT, LOGGED_OUT, TEMPORARY_BAN, STREAM_ERROR", "example": "TEMPORARY_BAN" }, "banCode": { "type": "integer", "minimum": 0, "description": "WhatsApp temporary-ban code (present only when statusReason is TEMPORARY_BAN).", "example": 101 }, "banReason": { "type": "string", "description": "Human-readable label for the ban code (present only when statusReason is TEMPORARY_BAN).", "example": "Suspected spam activity" }, "banExpiresAt": { "type": "integer", "description": "Unix timestamp in seconds when the temporary ban lifts, when WhatsApp provides a duration.", "format": "int64", "example": 1789000000 }, "detail": { "type": "string", "description": "Extra context for FAILED and STREAM_ERROR statuses (for example the connect-failure reason)." } }, "required": [ "status" ] }, "CloudAccountStatusPayload": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "meta" ], "description": "Always `meta`: a WhatsApp Business Account notification, not a connection-state change" }, "kind": { "type": "string", "enum": [ "account_alerts", "account_update", "phone_number_name_update" ], "description": "WhatsApp notification field that produced the event" }, "wabaId": { "type": "string", "description": "WhatsApp Business Account id the notification belongs to", "example": "102290129340398" }, "value": { "type": "object", "additionalProperties": {}, "description": "The notification's `value` object exactly as WhatsApp sent it; its fields vary by notification" } }, "required": [ "source", "kind", "value" ] }, "SessionStatusPayload": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeSessionStatusPayload" }, { "$ref": "#/components/schemas/CloudAccountStatusPayload" } ] }, "SessionStatusEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "session.status" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/SessionStatusPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "SessionConnectedPayload": { "type": "object", "properties": { "phoneNumber": { "type": "string" }, "id": { "type": "string", "description": "Polymorfa ID of the connected account." }, "pushName": { "type": "string" }, "phonePlatform": { "type": "string", "enum": [ "android", "ios", "meta_cloud", "unknown" ], "description": "Where the account's primary WhatsApp client runs.", "x-enumDescriptions": { "android": "WhatsApp or WhatsApp Business on an Android phone.", "ios": "WhatsApp or WhatsApp Business on an iPhone.", "meta_cloud": "Meta hosts the number through Cloud API.", "unknown": "The phone has not reported a recognized platform." } }, "accountType": { "type": "string", "enum": [ "whatsapp_app", "business_app", "meta_cloud", "meta_coexistence" ], "description": "How the account uses WhatsApp.", "x-enumDescriptions": { "whatsapp_app": "WhatsApp app, connected as a linked device.", "business_app": "WhatsApp Business app, connected as a linked device.", "meta_cloud": "Meta Cloud API.", "meta_coexistence": "Meta Cloud API, with the WhatsApp Business app still active on the phone." } }, "businessName": { "type": "string" } }, "required": [ "phoneNumber", "pushName", "phonePlatform", "accountType" ] }, "SessionConnectedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "session.connected" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/SessionConnectedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "SessionLoggedOutPayload": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "banned", "device_removed", "unknown" ], "description": "Why the session was logged out: `banned` when WhatsApp banned the account, `device_removed` when the linked device was removed from the phone or from another device, `unknown` otherwise (including a locked account).", "example": "device_removed" }, "code": { "type": "integer", "description": "WhatsApp's logout code: 401 (removed), 403 (locked) or 406 (banned); 0 when WhatsApp gave none.", "example": 401 } }, "required": [ "reason", "code" ] }, "SessionLoggedOutEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "session.logged_out" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/SessionLoggedOutPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "SessionPhoneOfflinePayload": { "type": "object", "properties": { "daysSinceLastSeen": { "type": "number", "description": "Whole days since the phone was last seen online.", "example": 11 }, "daysRemaining": { "type": "number", "description": "Days remaining before WhatsApp disconnects the session (clamped to 0). WhatsApp typically severs the companion link after ~14 days of phone inactivity.", "example": 3 }, "lastSeen": { "type": "string", "description": "ISO 8601 timestamp of the last time the phone was seen online.", "example": "2026-04-05T14:30:00Z" }, "action": { "type": "string", "description": "Human-readable action string to surface to the end user (e.g. ask them to open WhatsApp on their phone).", "example": "Open WhatsApp on your phone to keep the session alive" } }, "required": [ "daysSinceLastSeen", "daysRemaining", "lastSeen", "action" ] }, "SessionPhoneOfflineEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "session.phone_offline" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/SessionPhoneOfflinePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "SessionRestrictionUpdatedPayload": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reachout_timelock" ], "description": "The restriction. `reachout_timelock`: the number can only message or call people it has already chatted with.", "example": "reachout_timelock" }, "active": { "type": "boolean", "description": "True while the restriction applies.", "example": true }, "enforcementType": { "type": "string", "nullable": true, "description": "WhatsApp's category for the restriction; null when inactive or not reported.", "example": "DEFAULT" }, "expiresAt": { "type": "string", "nullable": true, "description": "When the restriction ends (ISO 8601); null when inactive or WhatsApp gave no end.", "example": "2026-09-20T08:00:00Z" }, "observedAt": { "type": "string", "description": "When the state was observed (ISO 8601).", "example": "2026-09-19T08:00:00Z" } }, "required": [ "type", "active", "enforcementType", "expiresAt", "observedAt" ] }, "SessionRestrictionUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "session.restriction_updated" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/SessionRestrictionUpdatedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "OfficialGroupError": { "type": "object", "properties": { "code": { "type": "integer", "description": "WhatsApp error code, for example `131215` (number not eligible for groups)." }, "title": { "type": "string" } }, "required": [ "code" ] }, "GroupUpdatePayload": { "type": "object", "properties": { "id": { "type": "string" }, "newSubject": { "type": "string" }, "newDescription": { "type": "string" }, "action": { "type": "string", "description": "What changed, for example `joined` when the Number joins a group with an invite link." }, "requestId": { "type": "string", "description": "Official groups: the `requestId` returned when the group was created, or WhatsApp's request ID for a change." }, "inviteLink": { "type": "string", "description": "Official groups, action `created`: the link people open to join the group." }, "joinApprovalRequired": { "type": "boolean", "description": "Official groups, action `created`: whether joining needs your approval." }, "pictureChanged": { "type": "boolean", "description": "Official groups, action `settings_updated`: true when WhatsApp applied a new group picture." }, "failedChanges": { "type": "array", "items": { "type": "string", "enum": [ "subject", "description", "picture" ] }, "description": "Official groups, action `settings_updated`: changes WhatsApp did not apply." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialGroupError" }, "description": "Official groups: why WhatsApp refused the operation." } }, "required": [ "id" ] }, "GroupUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "group.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/GroupUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "GroupParticipantPayload": { "type": "object", "properties": { "id": { "type": "string" }, "joined": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRef" } }, "left": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRef" } }, "promoted": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRef" } }, "demoted": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRef" } }, "reason": { "type": "string", "description": "Official groups: how the change happened as WhatsApp reported it, for example `invite_link`." }, "initiatedBy": { "type": "string", "enum": [ "business", "participant" ], "description": "Official groups: whether your business removed the participants or a participant left." }, "requestId": { "type": "string" }, "failedParticipants": { "type": "array", "items": { "type": "object", "properties": { "participant": { "$ref": "#/components/schemas/IdentityRef" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialGroupError" } } }, "required": [ "participant" ] }, "description": "Official groups: participants WhatsApp could not remove." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialGroupError" } }, "joinRequest": { "type": "object", "properties": { "joinRequestId": { "type": "string" }, "user": { "$ref": "#/components/schemas/IdentityRef" }, "state": { "type": "string", "enum": [ "created", "revoked" ] } }, "required": [ "joinRequestId", "user", "state" ], "description": "Official groups that require join approval: a person requested to join (`created`) or withdrew the request (`revoked`). Approve or reject it with the join request routes." } }, "required": [ "id" ] }, "GroupParticipantEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "group.participant" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/GroupParticipantPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "PresenceUpdatePayload": { "type": "object", "properties": { "observedAt": { "type": "integer" }, "from": { "$ref": "#/components/schemas/IdentityRef" }, "sender": { "$ref": "#/components/schemas/IdentityRef" }, "state": { "type": "string" }, "media": { "type": "string" }, "unavailable": { "type": "boolean" }, "lastSeen": { "type": "number" } }, "required": [ "observedAt" ] }, "PresenceUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "presence.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/PresenceUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ContactUpdatePayload": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "bsuid": { "type": "string" }, "phoneNumber": { "type": "string" }, "username": { "type": "string" }, "fullName": { "type": "string" }, "firstName": { "type": "string" }, "pushName": { "type": "string" }, "oldPushName": { "type": "string" }, "businessName": { "type": "string" }, "oldBusinessName": { "type": "string" }, "pictureId": { "type": "string" }, "pictureRemoved": { "type": "boolean" } }, "required": [ "id" ] }, "ContactUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "contact.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ContactUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ContactOptPayload": { "type": "object", "properties": { "phone": { "type": "string", "description": "Contact phone number in E.164 format", "example": "+14155550123" }, "source": { "type": "string", "enum": [ "stop-keyword" ], "description": "How the suppression list changed. Keyword replies always report `stop-keyword`." }, "keyword": { "type": "string", "description": "The configured keyword the reply matched, in upper case. The message itself is never included.", "example": "STOP" }, "session": { "type": "string", "description": "Session name of the number that received the reply", "example": "sales-1" }, "projectId": { "type": "string", "description": "Project that owns the receiving number, when known" } }, "required": [ "phone", "source", "keyword", "session" ] }, "ContactOptedOutEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "contact.opted_out" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ContactOptPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ContactOptedInEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "contact.opted_in" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ContactOptPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ChatArchivePayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "archive": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "required": [ "from" ] }, "ChatArchiveEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "chat.archive" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ChatArchivePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ChatMutePayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "muted": { "type": "boolean" }, "muteEndTimestamp": { "type": "number" } }, "required": [ "from", "muted" ] }, "ChatMuteEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "chat.mute" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ChatMutePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ChatReadPayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "read": { "type": "boolean" } }, "required": [ "from", "read" ] }, "ChatReadEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "chat.read" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ChatReadPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ChatClearPayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" } }, "required": [ "from" ] }, "ChatClearEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "chat.clear" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ChatClearPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ChatDeletePayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" } }, "required": [ "from" ] }, "ChatDeleteEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "chat.delete" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ChatDeletePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallReceivedPayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "callId": { "type": "string" }, "hasVideo": { "type": "boolean", "description": "Whether the offered call advertised video.", "example": false }, "sessionConnection": { "type": "string", "enum": [ "linked_device", "cloud_api" ], "description": "Connection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.", "example": "linked_device" }, "capabilities": { "type": "object", "properties": { "video": { "type": "boolean", "description": "The call can carry video." }, "invite": { "type": "boolean", "description": "More participants can be invited into the call." } }, "required": [ "video", "invite" ], "description": "What the call supports." } }, "required": [ "from", "callId", "hasVideo" ] }, "CallReceivedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.received" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallReceivedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallMissedPayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "callId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "from", "callId", "reason" ] }, "CallMissedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.missed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallMissedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallAcceptedPayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "callId": { "type": "string" }, "answeredBy": { "type": "string", "description": "Participant reference that answered or placed the call: `client:` or `server:`.", "example": "client:agent-7" }, "exclusive": { "type": "boolean", "description": "Present and `true` when the answering participant claimed the call." }, "sessionConnection": { "type": "string", "enum": [ "linked_device", "cloud_api" ], "description": "Connection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.", "example": "linked_device" }, "capabilities": { "type": "object", "properties": { "video": { "type": "boolean", "description": "The call can carry video." }, "invite": { "type": "boolean", "description": "More participants can be invited into the call." } }, "required": [ "video", "invite" ], "description": "What the call supports." } }, "required": [ "from", "callId" ] }, "CallAcceptedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.accepted" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallAcceptedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallRejectedPayload": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/IdentityRef" }, "callId": { "type": "string" } }, "required": [ "from", "callId" ] }, "CallRejectedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.rejected" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallRejectedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallEndedPayload": { "type": "object", "properties": { "from": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id" ] }, "callId": { "type": "string" }, "durationSeconds": { "type": "integer", "description": "Total connected duration in seconds (0 if never answered).", "example": 42 }, "reason": { "type": "string", "description": "Termination reason: user_hangup | timeout | lost_connection | rejected | capacity | pod_lost | connection_failed | upstream_failed | call_restricted (WhatsApp refused the call because the number is restricted to calling people it has already chatted with).", "example": "user_hangup" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Call direction.", "example": "inbound" }, "hadVideo": { "type": "boolean", "description": "Whether the call carried video.", "example": false }, "sessionConnection": { "type": "string", "enum": [ "linked_device", "cloud_api" ], "description": "Connection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.", "example": "linked_device" } }, "required": [ "from", "callId", "durationSeconds", "reason", "direction", "hadVideo" ] }, "CallEndedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.ended" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallEndedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallTelemetryPayload": { "type": "object", "properties": { "callId": { "type": "string" }, "setupMs": { "type": "integer", "description": "Time from offer to media_ready, in milliseconds.", "example": 850 }, "ringMs": { "type": "integer", "description": "Time spent ringing before accept, in milliseconds.", "example": 3200 }, "durationSeconds": { "type": "integer", "description": "Total connected duration in seconds.", "example": 42 }, "terminateReason": { "type": "string", "description": "Termination reason: user_hangup | timeout | lost_connection | rejected | capacity.", "example": "user_hangup" }, "codec": { "type": "string", "description": "Negotiated audio codec's bare subtype; empty when the audio stream does not identify its codec.", "example": "opus" }, "jitterMs": { "type": "number", "description": "Inbound RTP jitter for the audio stream, in milliseconds.", "example": 12.5 }, "packetsLost": { "type": "integer", "description": "Cumulative inbound RTP packets lost for the audio stream.", "example": 3 }, "rttMs": { "type": "number", "description": "Estimated round-trip time from the remote-inbound report, in milliseconds.", "example": 48.2 }, "recvKbps": { "type": "number", "description": "Total inbound volume across all RTP streams, in kilobits (cumulative).", "example": 2048 }, "sendKbps": { "type": "number", "description": "Total outbound volume across all RTP streams, in kilobits (cumulative).", "example": 2011 } }, "required": [ "callId", "setupMs", "ringMs", "durationSeconds", "terminateReason", "codec", "jitterMs", "packetsLost", "rttMs", "recvKbps", "sendKbps" ] }, "CallTelemetryEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.telemetry" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallTelemetryPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallParticipant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "handRaised": { "type": "boolean", "description": "Whether this participant has raised their hand when reported by the call roster." }, "audioMuted": { "type": "boolean", "enum": [ false ], "description": "Reserved; false until WhatsApp exposes authoritative participant mute state." }, "video": { "type": "boolean", "enum": [ false ], "description": "Reserved; false until WhatsApp exposes authoritative participant video state." }, "state": { "type": "string", "enum": [ "invited", "ringing", "connected", "left" ] } }, "required": [ "id", "audioMuted", "video", "state" ] }, "CallParticipantPayload": { "type": "object", "properties": { "callId": { "type": "string" }, "participant": { "$ref": "#/components/schemas/CallParticipant" } }, "required": [ "callId", "participant" ] }, "CallParticipantJoinedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.participant_joined" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallParticipantPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallParticipantStateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.participant_state" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallParticipantPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallParticipantLeftPayload": { "type": "object", "properties": { "callId": { "type": "string" }, "participantId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "callId", "participantId" ] }, "CallParticipantLeftEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.participant_left" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallParticipantLeftPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallConnection": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen connection identifier.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^(?:client|server):[A-Za-z0-9._:@-]{1,128}$", "description": "Participant reference: `client:` for a client token or `server:` for a server credential.", "example": "client:agent-7" }, "transport": { "type": "string", "enum": [ "webrtc", "socket", "sip" ], "description": "`webrtc` for a browser connection, `socket` for a server or app connection, `sip` for a SIP trunk." } }, "required": [ "id", "participant", "transport" ] }, "CallConnectionJoinedPayload": { "type": "object", "properties": { "callId": { "type": "string" }, "connection": { "$ref": "#/components/schemas/CallConnection" } }, "required": [ "callId", "connection" ] }, "CallConnectionJoinedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.connection_joined" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallConnectionJoinedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ConversationIdentity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "bsuid": { "type": "string", "pattern": "^[A-Z]{2}\\.[A-Za-z0-9]{1,128}$" }, "username": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id" ], "additionalProperties": false }, "CallPermissionChangedPayload": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ConversationIdentity" }, "status": { "type": "string", "enum": [ "none", "temporary", "permanent", "revoked" ], "description": "`temporary`: granted until `expiresAt`. `permanent`: granted without expiry. `revoked`: declined or withdrawn. `none`: no permission." }, "previousStatus": { "type": "string", "enum": [ "none", "temporary", "permanent", "revoked" ] }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When a temporary permission ends; null otherwise. No event is sent when it ends." }, "source": { "type": "string", "enum": [ "user_action", "automatic", "sync", "call_refused" ], "description": "`user_action`: the person answered a call permission request or changed it in WhatsApp. `automatic`: WhatsApp granted it when the person called you, or withdrew it after unanswered calls. `sync`: a permission read found a different state. `call_refused`: WhatsApp refused a call for lack of permission." }, "changedAt": { "type": "string", "format": "date-time" } }, "required": [ "conversation", "status", "previousStatus", "expiresAt", "source", "changedAt" ] }, "CallPermissionChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.permission_changed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallPermissionChangedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CallConnectionLeftPayload": { "type": "object", "properties": { "callId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen connection identifier.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^(?:client|server):[A-Za-z0-9._:@-]{1,128}$", "description": "Participant reference: `client:` for a client token or `server:` for a server credential.", "example": "client:agent-7" }, "reason": { "type": "string", "enum": [ "left", "replaced", "claimed", "call_ended", "sip_busy", "sip_declined", "sip_no_answer", "sip_unavailable", "sip_auth_failed" ], "description": "`left`: the connection left. `replaced`: a reconnect reused the connection id. `claimed`: another participant claimed the call. `sip_busy`, `sip_declined`, `sip_no_answer`, `sip_unavailable` and `sip_auth_failed`: a SIP trunk did not join the call. `call_ended`: the call ended while a SIP trunk was still ringing. A SIP trunk that never joined the call (one of the `sip_*` reasons, or `call_ended` while it was still ringing) reports only `call.connection_left`, with no `call.connection_joined` before it. Connections still open when the call ends are closed by `call.ended` without a separate event.", "example": "left" } }, "required": [ "callId", "connectionId", "participant", "reason" ] }, "CallConnectionLeftEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "call.connection_left" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CallConnectionLeftPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "UsageRecordedPayload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Usage record id. Stable across revisions." }, "meter": { "type": "string", "enum": [ "call.duration", "call.cloud_pulses", "campaign.call", "tts.characters", "tts.seconds", "stt.seconds", "agent.seconds", "agent.tokens", "agent.provider_cost", "channels.peak", "storage.byte_days" ], "description": "What was measured. Calls produce `call.duration`, and outgoing Cloud API calls also `call.cloud_pulses`.", "example": "call.duration" }, "quantity": { "type": "number", "minimum": 0, "description": "Measured amount in `unit`.", "example": 42 }, "unit": { "type": "string", "enum": [ "second", "pulse", "call", "character", "token", "provider_unit", "channel", "byte_day" ], "example": "second" }, "dimensions": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Closed, per-meter attributes. Call meters carry `direction`, `upstream` (`linked_device` or `cloud_api`), `origin`, `participants`, `connections`, `sipLegs` and `video`.", "example": { "direction": "outbound", "upstream": "linked_device", "origin": "direct", "participants": 1, "connections": 1, "sipLegs": 0, "video": false } }, "keySource": { "type": "string", "enum": [ "none", "managed", "customer" ], "description": "Whose provider key produced the usage. `none` for calls." }, "sourceKind": { "type": "string", "enum": [ "call", "attempt", "flow_run", "conversation", "asset", "team" ] }, "sourceId": { "type": "string", "description": "The call id for call meters." }, "projectId": { "type": "string", "nullable": true, "format": "uuid" }, "session": { "type": "string", "nullable": true, "description": "The number (session name) the usage belongs to." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the usage happened. For calls, when the call ended." }, "recordedAt": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 1, "description": "Starts at 1. A higher revision of the same `id` replaces the earlier one." }, "pricingState": { "type": "string", "enum": [ "unpriced", "priced", "waived", "settled" ], "description": "`unpriced` while usage is measured but not charged." }, "rateCard": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" } }, "required": [ "id", "version" ] }, "pricedCredits": { "type": "number", "nullable": true } }, "required": [ "id", "meter", "quantity", "unit", "dimensions", "keySource", "sourceKind", "sourceId", "projectId", "session", "occurredAt", "recordedAt", "revision", "pricingState", "rateCard", "pricedCredits" ] }, "UsageRecordedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "usage.recorded" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/UsageRecordedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "NewsletterUpdatePayload": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "muted": { "type": "boolean" } }, "required": [ "id", "action" ] }, "NewsletterUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "newsletter.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/NewsletterUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "BlocklistChange": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "bsuid": { "type": "string" }, "phoneNumber": { "type": "string" }, "username": { "type": "string" }, "action": { "type": "string" } }, "required": [ "id", "action" ] }, "BlocklistUpdatePayload": { "type": "object", "properties": { "action": { "type": "string" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/BlocklistChange" } } }, "required": [ "action", "changes" ] }, "BlocklistUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "blocklist.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/BlocklistUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "LabelsUpdatePayload": { "type": "object", "properties": { "action": { "type": "string", "description": "Action: label_edit, label_association_chat, label_association_message, star", "example": "label_edit" }, "labelId": { "type": "string", "description": "Label ID affected by the action" }, "from": { "allOf": [ { "$ref": "#/components/schemas/IdentityRef" }, { "description": "Chat the label action applies to" } ] }, "label": { "type": "string", "description": "Legacy field: the label's display name for label_edit, and the label ID for association actions. Prefer labelId and name." }, "name": { "type": "string", "description": "Label display name (present for label_edit)" }, "color": { "type": "integer", "description": "Label color index (present for label_edit)", "format": "int32" }, "orderIndex": { "type": "integer", "description": "Label ordering index when supplied by app state", "format": "int32" }, "deleted": { "type": "boolean", "description": "Whether the label definition was deleted" }, "labeled": { "type": "boolean", "description": "Whether the chat or message association is active" }, "observedAt": { "type": "integer", "description": "Unix timestamp in seconds when the app-state mutation was observed", "format": "int64" }, "messageId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Polymorfa message ID (present for star and message-association actions)", "example": "739182640518203" }, "starred": { "type": "boolean", "description": "Whether the message is starred (present for star actions)" } }, "required": [ "action" ] }, "LabelsUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "labels.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/LabelsUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "BusinessQuickReplyUpdatePayload": { "type": "object", "properties": { "id": { "type": "string" }, "shortcut": { "type": "string" }, "message": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer", "minimum": 0 }, "deleted": { "type": "boolean" }, "associatedLabelIds": { "type": "array", "items": { "type": "string" } }, "observedAt": { "type": "integer" }, "fromFullSync": { "type": "boolean" } }, "required": [ "id", "shortcut", "message", "keywords", "count", "deleted", "associatedLabelIds", "observedAt", "fromFullSync" ] }, "BusinessQuickReplyUpdateEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "business.quick_reply.update" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/BusinessQuickReplyUpdatePayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "ContactsSyncPayload": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "contacts" ] }, "value": { "type": "object", "additionalProperties": {} } }, "required": [ "kind", "value" ] }, "ContactsSyncEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "contact.sync" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/ContactsSyncPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "MessageEchoPayload": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "whatsapp_business_app" ] }, "value": { "type": "object", "additionalProperties": {} } }, "required": [ "source", "value" ] }, "MessageEchoEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.echo" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageEchoPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "LinkedHistorySyncPayload": { "type": "object", "properties": { "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "original_whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "original_whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular original provider reference for older consumers. Use original_whatsapp_ids for transport-specific references.", "deprecated": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/IdentityRef" }, "fromMe": { "type": "boolean" } }, "required": [ "id", "whatsapp_ids", "conversation" ] } }, "mode": { "type": "string", "enum": [ "deliver" ] }, "syncType": { "type": "string" }, "chunkOrder": { "type": "integer", "minimum": 0 }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "fileLength": { "type": "integer", "minimum": 0 }, "conversationCount": { "type": "integer", "minimum": 0 }, "messageCount": { "type": "integer", "minimum": 0 }, "pushNameCount": { "type": "integer", "minimum": 0 }, "statusMessageCount": { "type": "integer", "minimum": 0 }, "whatsapp": { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "gzip-base64-protobuf" ] }, "data": { "type": "string" } }, "required": [ "encoding", "data" ], "description": "Unmodified provider archive. Its protobuf retains provider addresses; use messages for Polymorfa identities." } }, "required": [ "whatsapp_ids", "messages", "mode", "syncType", "fileLength", "conversationCount", "messageCount", "pushNameCount", "statusMessageCount", "whatsapp" ] }, "CloudHistorySyncPayload": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "history" ] }, "value": { "type": "object", "additionalProperties": {} } }, "required": [ "kind", "value" ] }, "HistorySyncPayload": { "anyOf": [ { "$ref": "#/components/schemas/LinkedHistorySyncPayload" }, { "$ref": "#/components/schemas/CloudHistorySyncPayload" } ] }, "HistorySyncEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "history.sync" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/HistorySyncPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CommandResultPayload": { "type": "object", "properties": { "requestId": { "type": "string" }, "command": { "type": "string" }, "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": {} }, "error": { "type": "string" } }, "required": [ "requestId", "command", "success" ] }, "CommandResultEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "command.result" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CommandResultPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CustomerEnabledPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "migratedNumberCount": { "type": "integer", "minimum": 0 } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "migratedNumberCount" ], "additionalProperties": false }, "CustomerEnabledEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.enabled" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerEnabledPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerCreatedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind" ], "additionalProperties": false }, "CustomerCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.created" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerCreatedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerUpdatedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "phone", "externalCustomerId" ] }, "minItems": 1, "maxItems": 3 } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "fields" ], "additionalProperties": false }, "CustomerUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.updated" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerUpdatedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerArchivingPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "blockingNumberCount": { "type": "integer", "minimum": 0 }, "revokedPairingLinkCount": { "type": "integer", "minimum": 0 } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "blockingNumberCount", "revokedPairingLinkCount" ], "additionalProperties": false }, "CustomerArchivingEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.archiving" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerArchivingPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerArchivedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind" ], "additionalProperties": false }, "CustomerArchivedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.archived" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerArchivedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerRestoredPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind" ], "additionalProperties": false }, "CustomerRestoredEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.restored" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerRestoredPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerPairingLinkCreatedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "pairingLinkId": { "type": "string", "format": "uuid" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "pairingLinkId" ], "additionalProperties": false }, "CustomerPairingLinkCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.pairing_link.created" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerPairingLinkCreatedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerPairingLinkOpenedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "pairingLinkId": { "type": "string", "format": "uuid" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "pairingLinkId" ], "additionalProperties": false }, "CustomerPairingLinkOpenedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.pairing_link.opened" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerPairingLinkOpenedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerPairingLinkConnectedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "pairingLinkId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "pairingLinkId", "sessionId" ], "additionalProperties": false }, "CustomerPairingLinkConnectedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.pairing_link.connected" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerPairingLinkConnectedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerPairingLinkFailedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "pairingLinkId": { "type": "string", "format": "uuid" }, "errorCode": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "pairingLinkId", "errorCode" ], "additionalProperties": false }, "CustomerPairingLinkFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.pairing_link.failed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerPairingLinkFailedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerPairingLinkExpiredPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "pairingLinkId": { "type": "string", "format": "uuid" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "pairingLinkId" ], "additionalProperties": false }, "CustomerPairingLinkExpiredEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.pairing_link.expired" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerPairingLinkExpiredPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerPairingLinkRevokedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "pairingLinkId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "customer_archived", "phone_mismatch_limit", "exchange_failure_limit", "terminal_failure" ] } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "pairingLinkId" ], "additionalProperties": false }, "CustomerPairingLinkRevokedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.pairing_link.revoked" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerPairingLinkRevokedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerNumberAttachedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "sessionId": { "type": "string", "format": "uuid" }, "pairingLinkId": { "type": "string", "format": "uuid" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "sessionId" ], "additionalProperties": false }, "CustomerNumberAttachedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.number.attached" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerNumberAttachedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerNumberTransferredPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "sessionId": { "type": "string", "format": "uuid" }, "sourceCustomerId": { "type": "string", "format": "uuid" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "sessionId", "sourceCustomerId" ], "additionalProperties": false }, "CustomerNumberTransferredEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.number.transferred" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerNumberTransferredPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "CustomerNumberDisconnectedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "actorKind": { "type": "string", "enum": [ "better_auth", "org_key", "project_token", "cli_grant", "system" ] }, "sessionId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "customerId", "actorKind", "sessionId", "reason" ], "additionalProperties": false }, "CustomerNumberDisconnectedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "customer.number.disconnected" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CustomerNumberDisconnectedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "VoiceAssetReadyPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event ID for receiver idempotency." }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "assetId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "upload", "tts" ], "description": "`upload` or `tts`. Treat unknown values as `upload`." }, "durationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 (hex) of the converted 16 kHz mono PCM audio." }, "originalFormat": { "type": "string", "enum": [ "mp3", "wav", "ogg", "m4a" ] } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "assetId", "name", "source", "durationMs", "contentSha256", "originalFormat" ], "additionalProperties": false }, "VoiceAssetReadyEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "voice.asset_ready" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/VoiceAssetReadyPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "VoiceAssetFailedPayload": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event ID for receiver idempotency." }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "assetId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "upload", "tts" ], "description": "`upload` or `tts`. Treat unknown values as `upload`." }, "failureReason": { "type": "string", "enum": [ "unsupported_format", "too_large", "too_long", "decode_failed", "silent", "tts_failed", "processing_failed" ], "description": "Treat unknown values as `processing_failed`." } }, "required": [ "eventId", "occurredAt", "organizationId", "projectId", "assetId", "name", "source", "failureReason" ], "additionalProperties": false }, "VoiceAssetFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "voice.asset_failed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/VoiceAssetFailedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "BanSafeRequiredFinding": { "type": "object", "properties": { "findingKey": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$", "description": "Stable finding identifier.", "example": "typing_absent" }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Customer-facing finding title.", "example": "Messages sent without showing that you are typing" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] } }, "required": [ "findingKey", "title", "severity" ], "additionalProperties": false }, "BanSafeActionPayload": { "type": "object", "properties": { "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "The customer's own number in E.164 format.", "example": "+15551234567" }, "action": { "type": "string", "enum": [ "applied", "changed", "lifted", "daily_allowance_reached" ], "description": "Whether the restriction was newly applied, moved, or removed. `daily_allowance_reached` reports that the number spent its warm-up allowance for the day; nothing on the ladder moved and sending resumes at the next reset." }, "scope": { "type": "string", "enum": [ "number", "organization" ], "description": "Whether this covers one number or every number in the workspace." }, "rung": { "type": "string", "enum": [ "none", "notify", "throttle", "block_cold", "suspend" ], "description": "Restriction now in force." }, "previousRung": { "type": "string", "nullable": true, "enum": [ "none", "notify", "throttle", "block_cold", "suspend", null ], "description": "Restriction previously in force, or null when none was." }, "reason": { "type": "string", "enum": [ "health", "finding", "org_pattern", "repeat", "restriction", "operator", "health_model_cutover", "warmup" ], "description": "Why the restriction changed." }, "health": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100, "description": "Measured health from 0 (worst) to 100 (best), or null when not measured.", "example": 62 }, "healthBand": { "type": "string", "enum": [ "good", "fair", "poor", "failing", "unknown" ], "description": "Health band matching health." }, "requires": { "type": "array", "items": { "$ref": "#/components/schemas/BanSafeRequiredFinding" }, "maxItems": 25, "description": "Findings that must resolve before this restriction lifts." }, "throughputPerMinute": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 10000, "description": "Messages per minute allowed while paced, or null when not paced.", "example": 6 }, "eligibleLiftAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Earliest instant the restriction can step down, ISO 8601.", "example": "2026-09-08T14:00:00.000Z" }, "liftRequires": { "type": "string", "minLength": 1, "maxLength": 240, "description": "One sentence describing what lifts the restriction.", "example": "Resolve the two open checks and keep them clean for six evaluations." }, "appealUrl": { "type": "string", "maxLength": 500, "format": "uri", "description": "Where to appeal this action.", "example": "https://app.polymorfa.com/safety/appeal" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when this restriction took effect.", "example": "2026-09-06T14:00:00.000Z" }, "docs": { "type": "string", "maxLength": 500, "format": "uri", "description": "Documentation for this restriction.", "example": "https://docs.polymorfa.com/safety/restrictions" } }, "required": [ "phoneNumber", "action", "scope", "rung", "previousRung", "reason", "health", "healthBand", "requires", "throughputPerMinute", "eligibleLiftAt", "liftRequires", "appealUrl", "startedAt", "docs" ], "additionalProperties": false }, "BanSafeActionEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "bansafe.action" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/BanSafeActionPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "BanSafeHealthThresholdPayload": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "description": "Session whose present Health crossed the project threshold." }, "projectId": { "type": "string", "format": "uuid", "description": "Project whose Health rule produced this action." }, "health": { "type": "number", "minimum": 0, "maximum": 100, "description": "Present Health; higher is healthier." }, "threshold": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Configured project threshold crossed by this evaluation." }, "healthSource": { "type": "string", "enum": [ "rules_v1", "ml_model" ], "description": "Estimator family used by the evaluation." }, "estimatorVersion": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Estimator version used by the evaluation." }, "modelVersion": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 128, "description": "Learned-model version, or null for a rules-based estimate." }, "evaluatedAt": { "type": "string", "format": "date-time", "description": "Evaluation time in ISO 8601 format." }, "policyVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Project Health rule version evaluated." }, "episodeId": { "type": "string", "format": "uuid", "description": "Stable below-threshold episode identifier." }, "actionId": { "type": "string", "format": "uuid", "description": "Stable event identity used for retries." } }, "required": [ "sessionId", "projectId", "health", "threshold", "healthSource", "estimatorVersion", "modelVersion", "evaluatedAt", "policyVersion", "episodeId", "actionId" ], "additionalProperties": false }, "BanSafeHealthThresholdEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "bansafe.health_threshold" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/BanSafeHealthThresholdPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "BanSafeIncidentPayload": { "type": "object", "properties": { "id": { "type": "string", "description": "Incident id. Stable, quotable, and the subject of a Ban Insurance claim.", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "The customer's own number in E.164 format.", "example": "+15551234567" }, "kind": { "type": "string", "enum": [ "cap_warning", "cap_reached", "timelock", "temporary_ban", "permanent_ban", "connect_blocked", "customer_report" ], "description": "What WhatsApp did, or customer_report when you reported it." }, "source": { "type": "string", "enum": [ "runtime", "customer" ], "description": "Whether Polymorfa observed it or you reported it." }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the restriction started.", "example": "2026-09-06T14:03:12.000Z" }, "endsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp when the restriction ends, or null when it has no end. A ban you report ends 24 hours after the time you give unless you report it again or Polymorfa observes the restriction itself.", "example": "2026-09-07T14:03:12.000Z" }, "belief": { "type": "number", "minimum": 0, "maximum": 1, "description": "How confident Polymorfa is that this restriction was real, from 0 to 1. A restriction WhatsApp announced is 1. A ban you report starts at 0.9 and moves once the number's own sending shows whether it was restricted.", "example": 1 }, "resolution": { "type": "string", "enum": [ "open", "corroborated", "contradicted", "phone_switch", "final" ], "description": "How the incident settled. open: still being decided. corroborated: a report and an observed restriction agree. contradicted: the number kept sending, so there was no restriction. phone_switch: the number moved to another phone. final: settled with the confidence shown." }, "claimId": { "type": "string", "nullable": true, "description": "The Ban Insurance claim this incident belongs to, or null when there is none.", "example": null }, "closedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp when you closed or retracted the report, or null.", "example": null } }, "required": [ "id", "phoneNumber", "kind", "source", "startedAt", "endsAt", "belief", "resolution", "claimId", "closedAt" ], "additionalProperties": false }, "BanSafeIncidentEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "bansafe.incident" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/BanSafeIncidentPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "BanSafeClaimPayload": { "type": "object", "properties": { "id": { "type": "string", "description": "Claim id. Stable and quotable.", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f22" }, "incidentId": { "type": "string", "description": "The incident this claim was filed against.", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "The customer's own number in E.164 format.", "example": "+15551234567" }, "status": { "type": "string", "enum": [ "filed", "under_review", "approved", "denied", "paid", "reversed" ], "description": "Where the claim sits. filed and under_review are open. approved means it was accepted, and with a zero amount that there was nothing to return. paid means the credits are on your balance. reversed means what Polymorfa knew about the ban changed afterwards and the credits were taken back." }, "verdict": { "type": "string", "enum": [ "other_device", "customer_conduct", "shared_network", "ours", "inconclusive" ], "description": "What the ban was attributed to. other_device: another device on the account was sending. customer_conduct: Polymorfa was already restricting this number, or named the same serious problem for a week. shared_network: the number shared its connection with numbers that were being restricted. ours: nothing points at how the number was used. inconclusive: Polymorfa could not see enough of the window to say." }, "windowStart": { "type": "string", "format": "date-time", "description": "ISO 8601 start of the 30 days the refund covers.", "example": "2026-08-07T14:03:12.000Z" }, "windowEnd": { "type": "string", "format": "date-time", "description": "ISO 8601 end of the window: the moment the ban started.", "example": "2026-09-06T14:03:12.000Z" }, "measuredCents": { "type": "number", "description": "Credit quantity this number consumed inside the window, with up to six decimal places.", "minimum": 0, "multipleOf": 0.000001, "example": 1080 }, "capCents": { "type": "number", "description": "Maximum credit quantity this claim can return, with up to six decimal places.", "minimum": 0, "multipleOf": 0.000001, "example": 1080 }, "amountCents": { "type": "number", "description": "Credit quantity this claim returns, with up to six decimal places.", "minimum": 0, "multipleOf": 0.000001, "example": 1080 }, "summary": { "type": "string", "description": "One sentence describing the claim's state." }, "reason": { "type": "string", "description": "One sentence describing what the ban was attributed to." }, "decidedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp of the decision, or null while none was taken.", "example": null }, "paidAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp the credits landed, or null.", "example": null } }, "required": [ "id", "incidentId", "phoneNumber", "status", "verdict", "windowStart", "windowEnd", "measuredCents", "capCents", "amountCents", "summary", "reason", "decidedAt", "paidAt" ], "additionalProperties": false }, "BanSafeClaimEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "bansafe.claim" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/BanSafeClaimPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ], "additionalProperties": false }, "MessageFailedPayload": { "type": "object", "properties": { "to": { "allOf": [ { "$ref": "#/components/schemas/IdentityRef" }, { "description": "Recipient chat the send was attempted to" } ] }, "type": { "type": "string", "description": "Type of the attempted message (text, image, ...)", "example": "text" }, "error": { "type": "string", "enum": [ "invalid_recipient", "session_not_connected", "ack_timeout", "send_failed", "blocked_by_safety" ], "description": "Sanitized failure class", "example": "send_failed" }, "code": { "type": "string", "description": "Stable machine-readable code from the API error envelope, present for classified safety refusals and an unknown send outcome", "example": "bansafe_cold_blocked" }, "retryAfter": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Whole seconds to wait before retrying a paced send, exhausted allowance, or temporary allowance-accounting pause", "example": 5 }, "timestamp": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the failure occurred", "example": 1757161200 } }, "required": [ "to", "type", "error", "timestamp" ] }, "MessageFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "message.failed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/MessageFailedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "RuntimeTemplateStatusPayload": { "type": "object", "properties": { "templateName": { "type": "string", "description": "Template name as registered with Meta", "example": "order_update" }, "templateId": { "type": "string", "description": "Meta template id", "example": "1234567890" }, "status": { "type": "string", "description": "New approval status: APPROVED, REJECTED, PAUSED, DISABLED, DELETED", "example": "APPROVED" }, "category": { "type": "string", "description": "Template category (MARKETING, UTILITY, AUTHENTICATION)", "example": "UTILITY" }, "reason": { "type": "string", "description": "Reason for the status change; empty unless REJECTED, PAUSED or DISABLED", "example": "" }, "qualityRating": { "type": "string", "description": "Quality rating bucket reported by Meta (GREEN, YELLOW, RED)", "example": "GREEN" } }, "required": [ "templateName", "templateId", "status", "category", "reason", "qualityRating" ] }, "CloudTemplateStatusPayload": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "message_template_status_update", "message_template_quality_update" ], "description": "`message_template_status_update` for an approval change, `message_template_quality_update` for a quality change" }, "event": { "type": "string", "description": "New template status reported by WhatsApp; for a quality change, the new quality score", "example": "APPROVED" }, "templateId": { "type": "string", "description": "WhatsApp template id", "example": "1234567890" }, "templateName": { "type": "string", "description": "Template name", "example": "order_update" }, "language": { "type": "string", "description": "Template language code", "example": "en_US" }, "reason": { "type": "string", "description": "WhatsApp's explanation for the change, when supplied", "example": "NONE" }, "previousQualityScore": { "type": "string", "description": "Quality score before a quality change", "example": "GREEN" }, "newQualityScore": { "type": "string", "description": "Quality score after a quality change", "example": "YELLOW" }, "wabaId": { "type": "string", "description": "WhatsApp Business Account id that owns the template", "example": "102290129340398" } }, "required": [ "kind" ] }, "TemplateStatusPayload": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeTemplateStatusPayload" }, { "$ref": "#/components/schemas/CloudTemplateStatusPayload" } ] }, "TemplateStatusEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "template.status" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/TemplateStatusPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "OrderPaymentUpdatedPayload": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "payment_status", "payment_method_selected" ], "description": "`payment_status` when WhatsApp reports a payment status; `payment_method_selected` when the buyer confirmed a one-click payment method" }, "reportedBy": { "type": "string", "enum": [ "whatsapp" ], "description": "Polymorfa relays this report; it does not process or confirm funds" }, "providerEventId": { "type": "string", "description": "WhatsApp's notification or message ID" }, "referenceId": { "type": "string", "description": "Your order reference ID from the order details message", "example": "order-1522" }, "conversation": { "type": "object", "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" } }, "description": "The buyer" }, "status": { "type": "string", "description": "Payment status as WhatsApp reported it", "example": "captured" }, "amount": { "type": "object", "properties": { "value": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "value", "offset" ], "description": "Reported amount; value divided by offset is the amount in currency units" }, "currency": { "type": "string", "example": "BRL" }, "transaction": { "type": "object", "properties": { "id": { "type": "string" }, "providerTransactionId": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "method": { "type": "string" }, "errorCode": { "type": "string" } }, "description": "Payment provider transaction as WhatsApp reported it" }, "messageId": { "type": "string", "description": "Message that carried a payment method confirmation" }, "paymentMethod": { "type": "string", "example": "offsite_card_pay" }, "lastFourDigits": { "type": "string" }, "credentialId": { "type": "string", "description": "Your credential ID from the order's payment settings" }, "paymentTimestamp": { "type": "integer", "description": "Unix time in seconds reported by WhatsApp" } }, "required": [ "kind", "reportedBy", "providerEventId", "referenceId", "conversation" ] }, "OrderPaymentUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "order.payment_updated" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/OrderPaymentUpdatedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignPausedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "sentCount": { "type": "integer", "minimum": 0, "description": "Recipients sent so far" }, "remainingCount": { "type": "integer", "minimum": 0, "description": "Recipients still queued" }, "pausedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the campaign paused", "example": 1757161200 } }, "required": [ "campaignId", "sentCount", "remainingCount", "pausedAt" ] }, "CampaignPausedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.paused" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignPausedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignLaunchedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "name": { "type": "string" }, "recipientCount": { "type": "integer", "minimum": 0 }, "scheduled": { "type": "boolean" }, "launchedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in milliseconds when sending began" } }, "required": [ "campaignId", "name", "recipientCount", "scheduled", "launchedAt" ] }, "CampaignLaunchedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.launched" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignLaunchedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignResumedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "sentCount": { "type": "integer", "minimum": 0 }, "remainingCount": { "type": "integer", "minimum": 0 }, "resumedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in milliseconds when sending resumed" } }, "required": [ "campaignId", "sentCount", "remainingCount", "resumedAt" ] }, "CampaignResumedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.resumed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignResumedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignStoppedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "sentCount": { "type": "integer", "minimum": 0 }, "abandonedCount": { "type": "integer", "minimum": 0 }, "stoppedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in milliseconds when the stop settled" } }, "required": [ "campaignId", "sentCount", "abandonedCount", "stoppedAt" ] }, "CampaignStoppedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.stopped" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignStoppedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignRescheduledPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "previousScheduledAt": { "type": "integer", "nullable": true, "minimum": 0, "description": "The start time that was replaced, in Unix milliseconds" }, "scheduledAt": { "type": "integer", "minimum": 0, "description": "The new start time in Unix milliseconds. Equal to `rescheduledAt` when the campaign was asked to start now." }, "rescheduledAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in milliseconds when the new start time was accepted" } }, "required": [ "campaignId", "previousScheduledAt", "scheduledAt", "rescheduledAt" ] }, "CampaignRescheduledEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.rescheduled" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignRescheduledPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignCompletedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "skippedCount": { "type": "integer", "minimum": 0 }, "responseCount": { "type": "integer", "minimum": 0 }, "completedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the last recipient settled", "example": 1757161200 }, "durationMs": { "type": "integer", "minimum": 0, "description": "Wall-clock duration from launch to completion, in milliseconds" } }, "required": [ "campaignId", "sentCount", "deliveredCount", "readCount", "failedCount", "skippedCount", "responseCount", "completedAt", "durationMs" ] }, "CampaignCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.completed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignCompletedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignFailedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "reason": { "type": "string", "description": "Stable reason the campaign failed", "example": "all_recipients_failed" }, "failedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the campaign failed", "example": 1757161200 } }, "required": [ "campaignId", "reason", "failedAt" ] }, "CampaignFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.failed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignFailedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignRecipientSentPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "recipientId": { "type": "string", "description": "Campaign recipient id", "example": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66" }, "phone": { "type": "string", "description": "Recipient phone number in E.164", "example": "+14155550123" }, "sessionKey": { "type": "string", "description": "Sending number's session key", "example": "sales-1" }, "externalMessageId": { "type": "string", "description": "WhatsApp message id of the delivered send", "example": "3EB0A1B2C3D4E5F60718" }, "variantKey": { "type": "string", "description": "Content variant used for this recipient", "example": "v1" }, "attempt": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Attempt number that succeeded", "example": 1 } }, "required": [ "campaignId", "recipientId", "phone", "sessionKey", "externalMessageId", "variantKey", "attempt" ] }, "CampaignRecipientSentEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.recipient_sent" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignRecipientSentPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignRecipientFailedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "recipientId": { "type": "string", "description": "Campaign recipient id", "example": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66" }, "phone": { "type": "string", "description": "Recipient phone number in E.164", "example": "+14155550123" }, "attempts": { "type": "integer", "minimum": 0, "description": "Attempts made before giving up" }, "error": { "type": "string", "description": "Sanitized failure class or stable code", "example": "ack_timeout" }, "failedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the recipient was marked failed", "example": 1757161200 } }, "required": [ "campaignId", "recipientId", "phone", "attempts", "error", "failedAt" ] }, "CampaignRecipientFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.recipient_failed" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignRecipientFailedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignRecipientSkippedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "recipientId": { "type": "string", "description": "Campaign recipient id", "example": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66" }, "phone": { "type": "string", "description": "Recipient phone number in E.164", "example": "+14155550123" }, "reason": { "type": "string", "description": "Stable skip reason (skipped-optout, skipped-error, skipped-cold)", "example": "skipped-cold" }, "skippedAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the recipient was skipped", "example": 1757161200 } }, "required": [ "campaignId", "recipientId", "phone", "reason", "skippedAt" ] }, "CampaignRecipientSkippedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.recipient_skipped" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignRecipientSkippedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignThrottledPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "sessionKey": { "type": "string", "description": "Sending number's session key", "example": "sales-1" }, "reason": { "type": "string", "description": "Why sending was paced: `paced`, `bansafe_throttled`, `daily_allowance_reached`, or `new_chat_limit_reached` (WhatsApp capped this number's new chats for the current cycle)", "example": "bansafe_throttled" }, "deferredCount": { "type": "integer", "minimum": 0, "description": "Recipients deferred in this pass" }, "at": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds of the pacing decision", "example": 1757161200 } }, "required": [ "campaignId", "sessionKey", "reason", "deferredCount", "at" ] }, "CampaignThrottledEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.throttled" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignThrottledPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignCapReachedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "sessionKey": { "type": "string", "description": "Sending number's session key", "example": "sales-1" }, "phone": { "type": "string", "description": "Sending number in E.164", "example": "+14155550100" }, "capType": { "type": "string", "description": "Which cap was reached: `hourly` or `daily` (the campaign's own caps), or `new_chat` (WhatsApp's per-number new-chat cap)", "example": "daily" }, "capLimit": { "type": "integer", "minimum": 0, "description": "The cap that was reached. For `new_chat`, the quota WhatsApp reported" }, "windowResetsAt": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the cap window resets. For `new_chat`, the end of WhatsApp's cycle, or of Polymorfa's one-hour hold when WhatsApp rejected a new chat without reporting a cycle", "example": 1757161200 }, "at": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds of the decision", "example": 1757161200 } }, "required": [ "campaignId", "sessionKey", "phone", "capType", "capLimit", "windowResetsAt", "at" ] }, "CampaignCapReachedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.cap_reached" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignCapReachedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "CampaignColdBlockedPayload": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Campaign id", "example": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11" }, "recipientId": { "type": "string", "description": "Campaign recipient id", "example": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66" }, "phone": { "type": "string", "description": "Recipient phone number in E.164", "example": "+14155550123" }, "surface": { "type": "string", "description": "Campaign surface", "example": "whatsapp" }, "reason": { "type": "string", "description": "Stable hold reason", "example": "bansafe_cold_held" }, "at": { "type": "integer", "minimum": 0, "description": "Unix timestamp in seconds when the recipient was held", "example": 1757161200 } }, "required": [ "campaignId", "recipientId", "phone", "surface", "reason", "at" ] }, "CampaignColdBlockedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "session": { "type": "string", "description": "Session that produced this event" }, "externalId": { "type": "string", "description": "Integrator reference from the QuickLink that created this session. Included on session lifecycle events when supplied." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "event": { "type": "string", "enum": [ "campaign.cold_blocked" ], "description": "Event type" }, "payload": { "$ref": "#/components/schemas/CampaignColdBlockedPayload" } }, "required": [ "id", "session", "timestamp", "event", "payload" ] }, "PingResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } }, "required": [ "status" ] }, "HealthCheck": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "error": { "type": "string" } }, "required": [ "status" ] }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "checks": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HealthCheck" } } }, "required": [ "status", "checks" ] }, "VersionResponse": { "type": "object", "properties": { "version": { "type": "string" }, "buildTime": { "type": "string" }, "env": { "type": "string" }, "apiVersion": { "type": "string" }, "minSupportedVersion": { "type": "string" } }, "required": [ "version", "buildTime", "env", "apiVersion", "minSupportedVersion" ] }, "StatusResponse": { "type": "object", "properties": { "status": { "type": "string" }, "uptime": { "type": "string" }, "version": { "type": "string" }, "env": { "type": "string" } }, "required": [ "status", "uptime", "version", "env" ] }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success" ] }, "QRResponse": { "type": "object", "properties": { "qr": { "type": "string", "description": "QR code data to encode into a scannable image" }, "event": { "type": "string", "description": "QR channel event (e.g. success, timeout)" } } }, "GetQRCodeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/QRResponse" } }, "required": [ "success", "data" ] }, "PairCodeResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Numeric pairing code for device linking" } }, "required": [ "code" ] }, "RequestPairCodeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PairCodeResponse" } }, "required": [ "success", "data" ] }, "PairCodeRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 1 } }, "required": [ "phone" ] }, "HybridRoutingPolicy": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "team", "project", "session" ] }, "revision": { "type": "string" }, "prefer": { "type": "string", "nullable": true, "enum": [ "linked_devices", "official_api", null ] }, "allowedTransports": { "type": "array", "items": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "maxItems": 2 } }, "required": [ "scope", "revision", "prefer", "allowedTransports" ] }, "HybridRoutingPolicyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/HybridRoutingPolicy" } }, "required": [ "success", "data" ] }, "PublicError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "conflict_error", "rate_limit_error", "api_error", "upstream_error" ] }, "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_credential", "entitlement_required", "cloud_template_authority_restricted", "gate_limit_reached", "method_not_allowed", "permission_denied", "missing_scope", "resource_not_found", "hms_not_enabled", "media_fetch_failed", "resource_gone", "feature_unavailable", "stream_cursor_invalid", "stream_cursor_expired", "stream_connection_limit_reached", "state_conflict", "hybrid_routing_paused", "hybrid_choice_required", "hybrid_transition_ineligible", "hybrid_automation_unavailable", "hybrid_transport_unavailable", "hybrid_target_reference_unavailable", "send_outcome_unknown", "idempotency_conflict", "idempotency_in_progress", "idempotency_completed", "idempotency_outcome_unknown", "call_claimed", "call_not_ringing", "connection_limit", "unsupported_for_connection", "call_permission_required", "invalid_sip_trunk", "calls_disabled", "call_recipient_opted_out", "call_destination_blocked", "call_permission_request_limited", "call_permission_granted", "order_status_transition_invalid", "order_cancellation_failed", "call_opt_out_limit", "number_restricted", "sip_trunk_in_use", "sip_trunk_revision_conflict", "sip_trunk_limit", "sip_unavailable", "voice_not_enabled", "provider_credential_invalid", "provider_unavailable", "asset_not_ready", "voice_asset_in_use", "voice_asset_revision_conflict", "voice_unavailable", "rate_limit_exceeded", "internal_error", "operation_not_supported", "upstream_failure", "service_unavailable", "credential_verification_unavailable", "session_not_ready", "command_dispatch_failed", "result_unknown", "recipient_not_on_whatsapp", "conversation_window_closed", "template_not_approved", "media_too_large", "whatsapp_rate_limited", "new_chat_limit_reached", "whatsapp_account_restricted", "whatsapp_groups_ineligible", "whatsapp_group_creation_paused", "whatsapp_group_limit_reached", "whatsapp_group_full", "whatsapp_group_suspended", "whatsapp_group_has_no_participants", "bansafe_suspended", "bansafe_org_suspended", "bansafe_cold_blocked", "bansafe_cold_held", "bansafe_throttled", "bansafe_daily_allowance_reached", "bansafe_accounting_unavailable", "bansafe_send_outcome_unknown", "campaigns_not_entitled", "campaign_throughput_capped" ] }, "message": { "type": "string" }, "param": { "type": "string", "nullable": true }, "request_id": { "type": "string", "description": "Matches the X-Request-Id response header. Include it when you contact support." }, "request_log_url": { "type": "string", "format": "uri", "description": "Console page that shows this request. Returned only to organization and project credentials whose request was logged." } }, "required": [ "type", "code", "message", "param", "request_id" ] }, "data": { "type": "string", "nullable": true, "enum": [ null ], "description": "Always null for a failed request." }, "docs": { "type": "string", "format": "uri" } }, "required": [ "error", "data", "docs" ] }, "SetHybridRoutingPolicy": { "type": "object", "properties": { "expectedRevision": { "anyOf": [ { "type": "string", "enum": [ "default" ] }, { "type": "string", "format": "uuid" } ] }, "prefer": { "type": "string", "nullable": true, "enum": [ "linked_devices", "official_api", null ] }, "allowedTransports": { "type": "array", "items": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "maxItems": 2 } }, "required": [ "expectedRevision", "prefer", "allowedTransports" ], "additionalProperties": false }, "HybridLinkState": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "paused": { "type": "boolean" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "status": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "kind", "status", "enabled" ] } } }, "required": [ "revision", "paused", "connections" ] }, "HybridLinkStateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/HybridLinkState" } }, "required": [ "success", "data" ] }, "HybridLinkPauseResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "paused": { "type": "boolean" } }, "required": [ "revision", "paused" ] } }, "required": [ "success", "data" ] }, "SentMessage": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "routingReason": { "type": "string", "enum": [ "explicit_transport", "template", "target_reference", "only_eligible_transport", "session_rule", "project_rule", "team_rule", "default_linked_devices" ] }, "operationId": { "type": "string", "format": "uuid" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "allOf": [ { "$ref": "#/components/schemas/ConversationIdentity" }, { "description": "The message's conversation, including its public ID and known aliases." } ] }, "timestamp": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "Upstream acceptance status. Delivery and read receipts arrive separately." }, "type": { "type": "string" }, "content": { "$ref": "#/components/schemas/MessageContent" }, "mediaId": { "type": "string" } }, "required": [ "id", "whatsapp_ids", "conversation", "timestamp", "status", "type", "content" ] }, "SendMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SentMessage" } }, "required": [ "success", "data" ] }, "AsyncAcceptedResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" } }, "required": [ "requestId" ] } }, "required": [ "success", "data" ] }, "ConversationReference": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "bsuid": { "type": "string", "pattern": "^[A-Z]{2}\\.[A-Za-z0-9]{1,128}$" }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Known username. This field alone does not select a conversation." } }, "additionalProperties": false, "anyOf": [ { "required": [ "id" ] }, { "required": [ "phoneNumber" ] }, { "required": [ "bsuid" ] } ] }, "QuotedMessage": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "type": { "type": "string" }, "text": { "type": "string" } }, "required": [ "id" ], "description": "Message being replied to." }, "PaymentOrderAmount": { "type": "object", "properties": { "value": { "type": "integer", "description": "Amount in centavos (value multiplied by offset). R$12.34 is 1234." }, "offset": { "type": "number", "enum": [ 100 ], "description": "Always 100 for BRL." } }, "required": [ "value", "offset" ], "additionalProperties": false, "description": "Amount the buyer pays. With `order`, equals subtotal + tax + shipping - discount." }, "OrderDetailsContent": { "type": "object", "properties": { "referenceId": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,60}$", "description": "Your unique order or invoice ID: 1 to 60 letters, digits, underscores, dashes or dots. Use a new ID for every order details message." }, "type": { "type": "string", "enum": [ "digital-goods", "physical-goods" ] }, "body": { "type": "string", "minLength": 1, "description": "Message text, at most 1,024 characters." }, "footer": { "type": "string", "minLength": 1, "description": "Footer text, at most 60 characters." }, "headerImageUrl": { "type": "string", "format": "uri", "description": "HTTPS image shown as the order thumbnail. Requires `order`." }, "currency": { "type": "string", "enum": [ "BRL" ] }, "totalAmount": { "$ref": "#/components/schemas/PaymentOrderAmount" }, "paymentSettings": { "type": "object", "properties": { "pixDynamicCode": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Dynamic Pix copy-and-paste code generated by your bank or payment provider." }, "merchantName": { "type": "string", "minLength": 1, "description": "Account holder name shown to the buyer." }, "key": { "type": "string", "minLength": 1, "description": "Pix key shown to the buyer." }, "keyType": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ] } }, "required": [ "code", "merchantName", "key", "keyType" ], "additionalProperties": false }, "paymentLink": { "type": "object", "properties": { "uri": { "type": "string", "format": "uri", "description": "HTTPS checkout link from your payment provider." } }, "required": [ "uri" ], "additionalProperties": false }, "boleto": { "type": "object", "properties": { "digitableLine": { "type": "string", "minLength": 1, "description": "Boleto digitable line: 47 or 48 digits." } }, "required": [ "digitableLine" ], "additionalProperties": false } }, "additionalProperties": false, "description": "At least one way to pay. Polymorfa does not process the payment.", "minProperties": 1 }, "order": { "type": "object", "properties": { "catalogId": { "type": "string", "minLength": 1 }, "expiration": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix time in seconds, at least 300 seconds from now." }, "description": { "type": "string", "minLength": 1, "description": "Why or when the order expires, at most 120 characters." } }, "required": [ "timestamp", "description" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "retailerId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "description": "At most 60 characters." }, "amount": { "allOf": [ { "$ref": "#/components/schemas/PaymentOrderAmount" }, { "description": "Price per item." } ] }, "quantity": { "type": "integer", "minimum": 1 }, "saleAmount": { "allOf": [ { "$ref": "#/components/schemas/PaymentOrderAmount" }, { "description": "Discounted price per item, below `amount`." } ] } }, "required": [ "retailerId", "name", "amount", "quantity" ], "additionalProperties": false }, "minItems": 1 }, "subtotal": { "allOf": [ { "$ref": "#/components/schemas/PaymentOrderAmount" }, { "description": "Sum of each item's saleAmount (or amount) times quantity." } ] }, "tax": { "type": "object", "properties": { "value": { "type": "integer", "description": "Amount in centavos (value multiplied by offset). R$12.34 is 1234." }, "offset": { "type": "number", "enum": [ 100 ], "description": "Always 100 for BRL." }, "description": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "value", "offset" ], "additionalProperties": false, "description": "Tax; value may be 0." }, "shipping": { "type": "object", "properties": { "value": { "type": "integer", "description": "Amount in centavos (value multiplied by offset). R$12.34 is 1234." }, "offset": { "type": "number", "enum": [ 100 ], "description": "Always 100 for BRL." }, "description": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "value", "offset" ], "additionalProperties": false }, "discount": { "type": "object", "properties": { "value": { "type": "integer", "description": "Amount in centavos (value multiplied by offset). R$12.34 is 1234." }, "offset": { "type": "number", "enum": [ 100 ], "description": "Always 100 for BRL." }, "description": { "type": "string", "minLength": 1 }, "programName": { "type": "string", "minLength": 1 } }, "required": [ "value", "offset" ], "additionalProperties": false } }, "required": [ "items", "subtotal", "tax" ], "additionalProperties": false, "description": "Itemized order. Omit to send only the total." } }, "required": [ "referenceId", "type", "body", "currency", "totalAmount", "paymentSettings" ], "additionalProperties": false, "description": "Brazil order with payment instructions (Official API only). Polymorfa relays the order; it does not collect, hold or confirm funds." }, "OrderStatusContent": { "type": "object", "properties": { "referenceId": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,60}$", "description": "The referenceId of the order details message." }, "body": { "type": "string", "minLength": 1, "description": "Message text, at most 1,024 characters." }, "footer": { "type": "string", "minLength": 1 }, "order": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "partially_shipped", "shipped", "completed", "canceled" ] }, "description": { "type": "string", "minLength": 1, "description": "At most 120 characters." } }, "required": [ "status" ], "additionalProperties": false }, "payment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "captured", "failed" ], "description": "Status confirmed by your payment provider. `captured` shows the order as paid." }, "timestamp": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "status" ], "additionalProperties": false } }, "required": [ "referenceId", "body" ], "additionalProperties": false, "description": "Update a Brazil order sent with orderDetails (Official API only). Send it after your payment provider confirms a payment status. Provide order, payment, or both.", "anyOf": [ { "required": [ "order" ] }, { "required": [ "payment" ] } ] }, "MessageContent": { "description": "Exactly one message kind: text, image, location, or another supported content field.", "oneOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Text to send." } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the media to send. Specify this or base64." }, "base64": { "type": "string", "minLength": 1, "description": "Base64-encoded media bytes. Specify this or url." }, "mimeType": { "type": "string", "description": "MIME type of the media." }, "caption": { "type": "string", "description": "Caption sent with the media." } }, "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "video": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the media to send. Specify this or base64." }, "base64": { "type": "string", "minLength": 1, "description": "Base64-encoded media bytes. Specify this or url." }, "mimeType": { "type": "string", "description": "MIME type of the media." }, "caption": { "type": "string", "description": "Caption sent with the media." } }, "additionalProperties": false } }, "required": [ "video" ], "additionalProperties": false }, { "type": "object", "properties": { "file": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the media to send. Specify this or base64." }, "base64": { "type": "string", "minLength": 1, "description": "Base64-encoded media bytes. Specify this or url." }, "mimeType": { "type": "string", "description": "MIME type of the media." }, "caption": { "type": "string", "description": "Caption sent with the media." }, "filename": { "type": "string" } }, "additionalProperties": false } }, "required": [ "file" ], "additionalProperties": false }, { "type": "object", "properties": { "voice": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the media to send. Specify this or base64." }, "base64": { "type": "string", "minLength": 1, "description": "Base64-encoded media bytes. Specify this or url." }, "mimeType": { "type": "string", "description": "MIME type of the media." }, "caption": { "type": "string", "description": "Caption sent with the media." }, "ptt": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "voice" ], "additionalProperties": false }, { "type": "object", "properties": { "location": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude in decimal degrees." }, "long": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude in decimal degrees." }, "address": { "type": "string", "description": "Display address for the location." } }, "required": [ "lat", "long" ], "additionalProperties": false } }, "required": [ "location" ], "additionalProperties": false }, { "type": "object", "properties": { "poll": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "options": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 2 }, "multiSelect": { "type": "boolean" } }, "required": [ "title", "options" ], "additionalProperties": false } }, "required": [ "poll" ], "additionalProperties": false }, { "type": "object", "properties": { "contact": { "type": "object", "properties": { "vcard": { "type": "string", "minLength": 1 } }, "required": [ "vcard" ], "additionalProperties": false } }, "required": [ "contact" ], "additionalProperties": false }, { "type": "object", "properties": { "requestPhoneNumber": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "requestPhoneNumber" ], "additionalProperties": false }, { "type": "object", "properties": { "product": { "type": "object", "properties": { "businessOwnerId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 0 }, "currencyCode": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceAmount1000": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "salePriceAmount1000": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "retailerId": { "type": "string", "minLength": 0 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "imageCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "image": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 4096, "format": "uri" }, "base64": { "type": "string", "maxLength": 87384 }, "mimeType": { "type": "string", "minLength": 0 } } }, "body": { "type": "string", "minLength": 0 }, "footer": { "type": "string", "minLength": 0 } }, "required": [ "businessOwnerId", "id", "title", "currencyCode", "priceAmount1000" ] } }, "required": [ "product" ], "additionalProperties": false }, { "type": "object", "properties": { "productList": { "type": "object", "properties": { "businessOwnerId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 0 }, "buttonText": { "type": "string", "minLength": 1 }, "footer": { "type": "string", "minLength": 0 }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 0 }, "productIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 30 } }, "required": [ "productIds" ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "businessOwnerId", "title", "buttonText", "sections" ] } }, "required": [ "productList" ], "additionalProperties": false }, { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "thumbnailBase64": { "type": "string", "maxLength": 87384 }, "itemCount": { "type": "integer", "minimum": 1, "maximum": 100 }, "status": { "type": "string", "enum": [ "inquiry", "accepted", "declined" ] }, "message": { "type": "string", "minLength": 0 }, "title": { "type": "string", "minLength": 0 }, "sellerId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "token": { "type": "string", "minLength": 0 }, "totalAmount1000": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCurrencyCode": { "type": "string", "pattern": "^[A-Z]{3}$" }, "catalogType": { "type": "string", "minLength": 0 } }, "required": [ "id", "itemCount", "status", "sellerId", "totalAmount1000", "totalCurrencyCode" ] } }, "required": [ "order" ], "additionalProperties": false }, { "type": "object", "properties": { "list": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 0 }, "buttonText": { "type": "string", "minLength": 1 }, "footer": { "type": "string", "minLength": 0 }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 0 }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 0 } }, "required": [ "id", "title" ] }, "minItems": 1, "maxItems": 30 } }, "required": [ "rows" ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "title", "buttonText", "sections" ], "description": "On an official WhatsApp Business number, `title` is the header (at most 60 characters) and `description` the body (at most 1,024 characters); without `description`, `title` is the body. There, each section title allows at most 24 characters and is required when the list has more than one section, lists allow at most 10 rows in total, row titles at most 24 characters, row IDs at most 200, row descriptions at most 72, `buttonText` at most 20 and `footer` at most 60. Every number also limits `buttonText` to 64 UTF-8 bytes, row `id` to 256 bytes and `title` and `description` to 256 and 4,096 bytes, so multibyte text reaches those byte limits before the character limits. Content outside any limit returns `400`." } }, "required": [ "list" ], "additionalProperties": false }, { "type": "object", "properties": { "buttons": { "type": "object", "properties": { "title": { "type": "string", "minLength": 0 }, "body": { "type": "string", "minLength": 1 }, "footer": { "type": "string", "minLength": 0 }, "buttons": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "text": { "type": "string", "minLength": 1 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "type", "text", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "call" ] }, "text": { "type": "string", "minLength": 1 }, "phoneNumber": { "type": "string", "pattern": "^\\+?\\d{6,20}$" } }, "required": [ "type", "text", "phoneNumber" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply" ] }, "text": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "text", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "copy" ] }, "text": { "type": "string", "minLength": 1 }, "copyCode": { "type": "string", "minLength": 1 } }, "required": [ "type", "text", "copyCode" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "catalog" ] }, "text": { "type": "string", "minLength": 1 }, "businessPhoneNumber": { "type": "string", "pattern": "^\\+?\\d{6,20}$" }, "catalogProductId": { "type": "string", "minLength": 0 } }, "required": [ "type", "text", "businessPhoneNumber" ] } ] }, "minItems": 1, "maxItems": 3 } }, "required": [ "body", "buttons" ], "description": "On an official WhatsApp Business number, only `reply` buttons are sent; other button types return `501`. There, `body` allows at most 1,024 characters, `title` and `footer` at most 60, and each button needs a unique `id` and a unique `text` of at most 20 characters. Every number also limits each button `id` to 256 UTF-8 bytes. Content outside any limit returns `400`." } }, "required": [ "buttons" ], "additionalProperties": false }, { "type": "object", "properties": { "addressMessage": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "buttonText": { "type": "string", "minLength": 1 }, "footer": { "type": "string", "minLength": 0 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "body" ] } }, "required": [ "addressMessage" ], "additionalProperties": false }, { "type": "object", "properties": { "flow": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "buttonText": { "type": "string", "minLength": 1 }, "footer": { "type": "string", "minLength": 0 }, "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "navigate", "data_exchange" ] }, "screen": { "type": "string", "minLength": 0 }, "dataJson": { "type": "string", "minLength": 0 } }, "required": [ "body", "buttonText", "id", "token", "action" ], "oneOf": [ { "properties": { "action": { "enum": [ "navigate" ] } }, "required": [ "screen" ] }, { "properties": { "action": { "enum": [ "data_exchange" ] } }, "not": { "anyOf": [ { "required": [ "screen" ] }, { "required": [ "dataJson" ] } ] } } ] } }, "required": [ "flow" ], "additionalProperties": false }, { "type": "object", "properties": { "callPermissionRequest": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Why you want to call, shown above WhatsApp's allow and decline buttons. 1 to 1,024 Unicode characters." } }, "required": [ "body" ], "additionalProperties": false, "description": "Ask the person for permission to call them. Cloud API numbers only; WhatsApp limits how often you can ask." } }, "required": [ "callPermissionRequest" ], "additionalProperties": false }, { "type": "object", "properties": { "orderDetails": { "$ref": "#/components/schemas/OrderDetailsContent" } }, "required": [ "orderDetails" ], "additionalProperties": false }, { "type": "object", "properties": { "orderStatus": { "$ref": "#/components/schemas/OrderStatusContent" } }, "required": [ "orderStatus" ], "additionalProperties": false }, { "type": "object", "properties": { "template": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 2 }, "components": { "type": "array", "items": {} } }, "required": [ "name", "language" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false } ] }, "SendMessageRequest": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "auto", "linked_devices", "official_api" ], "description": "Choose a transport or use the Number's routing rules. An explicit choice does not fall back." }, "conversation": { "$ref": "#/components/schemas/ConversationReference" }, "isForwarded": { "type": "boolean", "description": "Mark this message as forwarded." }, "mentions": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "description": "User IDs to mention in this message." }, "quotedMessage": { "$ref": "#/components/schemas/QuotedMessage" }, "content": { "$ref": "#/components/schemas/MessageContent" } }, "required": [ "conversation", "content" ], "additionalProperties": false, "description": "Specify conversation and content containing exactly one message kind. Shared options remain outside content." }, "MessageActionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "success", "data" ] }, "SeenRequest": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ConversationReference" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" } }, "required": [ "conversation", "id" ], "additionalProperties": false }, "TypingRequest": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ConversationReference" }, "state": { "type": "string", "enum": [ "typing", "recording", "paused" ] }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" } }, "required": [ "conversation", "state" ], "additionalProperties": false }, "MessageReceipt": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "routingReason": { "type": "string", "enum": [ "explicit_transport", "template", "target_reference", "only_eligible_transport", "session_rule", "project_rule", "team_rule", "default_linked_devices" ] }, "operationId": { "type": "string", "format": "uuid" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "allOf": [ { "$ref": "#/components/schemas/ConversationIdentity" }, { "description": "The message's conversation, including its public ID and known aliases." } ] }, "timestamp": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "Upstream acceptance status. Delivery and read receipts arrive separately." } }, "required": [ "id", "whatsapp_ids", "conversation", "timestamp", "status" ] }, "SendReactionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MessageReceipt" } }, "required": [ "success", "data" ] }, "ReactRequest": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "auto", "linked_devices", "official_api" ] }, "conversation": { "$ref": "#/components/schemas/ConversationReference" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "reaction": { "type": "string" } }, "required": [ "conversation", "id", "reaction" ], "additionalProperties": false }, "StarRequest": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ConversationReference" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "star": { "type": "boolean" } }, "required": [ "conversation", "id", "star" ], "additionalProperties": false }, "MessageOperation": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "unknown", "rejected", "completed" ] }, "transport": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "rejectionCode": { "type": "string", "enum": [ "hybrid_authority_unavailable" ] }, "receipt": { "type": "object", "properties": { "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "whatsapp_ids", "timestamp" ] } }, "required": [ "operationId", "status" ] }, "MessageOperationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MessageOperation" } }, "required": [ "success", "data" ] }, "EditMessageRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "transport": { "type": "string", "enum": [ "auto", "linked_devices", "official_api" ] } }, "required": [ "text" ] }, "DisappearingTimerRequest": { "type": "object", "properties": { "durationSeconds": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 86400 ] }, { "type": "number", "enum": [ 604800 ] }, { "type": "number", "enum": [ 7776000 ] } ] } }, "required": [ "durationSeconds" ] }, "HistoryMessageSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "whatsapp_ids", "direction", "type", "timestamp" ] }, "HistoryChat": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ConversationIdentity" }, "kind": { "type": "string", "enum": [ "direct", "group", "channel", "broadcast" ] }, "lastActivityAt": { "type": "string", "format": "date-time" }, "lastMessage": { "$ref": "#/components/schemas/HistoryMessageSummary" } }, "required": [ "conversation", "kind", "lastActivityAt", "lastMessage" ] }, "ListChatsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryChat" } }, "hasMore": { "type": "boolean", "description": "True when `nextCursor` returns more items." }, "nextCursor": { "type": "string", "nullable": true }, "previousCursor": { "type": "string", "nullable": true, "description": "Always null for conversations. Use nextCursor to continue listing." } }, "required": [ "success", "data", "hasMore", "nextCursor", "previousCursor" ] }, "GetChatResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/HistoryChat" } }, "required": [ "success", "data" ] }, "HistoryConversation": { "allOf": [ { "$ref": "#/components/schemas/ConversationIdentity" }, { "type": "object", "properties": { "sender": { "allOf": [ { "$ref": "#/components/schemas/ConversationIdentity" }, { "description": "Author of an inbound group message." } ] } }, "additionalProperties": false } ] }, "HistoryMedia": { "type": "object", "properties": { "id": { "type": "string", "description": "Media ID. Download the bytes from `url` with a credential that has `media:read`." }, "mimeType": { "type": "string" }, "fileLength": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "description": "Path of the media download method.", "example": "/messaging/media/0e6f1c3a-5a55-4f3c-9d4f-0b1f8f2a9c11" } }, "required": [ "id", "mimeType", "fileLength", "url" ] }, "HistoryMediaRetrieval": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "stored", "unavailable", "expired", "too_large", "unsupported_type", "failed", "cancelled" ], "description": "`pending`: the copy is not stored yet. `stored`: `media` lists the copy. Every other state is final and no copy will be stored." }, "reason": { "type": "string", "description": "Why a final state other than `stored` was reached, for example `provider_media_not_found` or `media_too_large`.", "example": "provider_media_expired" } }, "required": [ "state" ], "description": "Official API media only: whether a copy of the media was stored with this message." }, "HistoryMessage": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/HistoryConversation" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "fromMe": { "type": "boolean", "description": "True when the Number sent the message, including from another linked device." }, "type": { "type": "string", "description": "Message type as delivered in `message.received`, for example `text` or `image`." }, "timestamp": { "type": "string", "format": "date-time", "description": "When WhatsApp reported the message." }, "pushName": { "type": "string" }, "text": { "type": "string" }, "caption": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "ptt": { "type": "boolean" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "displayName": { "type": "string" }, "title": { "type": "string" }, "reaction": { "type": "string" }, "reactionTo": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "edited": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "unavailableReason": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "hash": { "type": "string" } }, "required": [ "name", "hash" ] } }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryMedia" }, "description": "Downloadable media for image, video, audio, document, and sticker messages. Empty when no copy is available." }, "mediaRetrieval": { "$ref": "#/components/schemas/HistoryMediaRetrieval" } }, "required": [ "id", "whatsapp_ids", "conversation", "direction", "fromMe", "type", "timestamp" ] }, "ListChatMessagesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryMessage" } }, "hasMore": { "type": "boolean", "description": "True when `nextCursor` returns more items." }, "nextCursor": { "type": "string", "nullable": true }, "previousCursor": { "type": "string", "nullable": true, "description": "Cursor for the preceding page of messages. Null when no preceding page exists." } }, "required": [ "success", "data", "hasMore", "nextCursor", "previousCursor" ] }, "GetChatMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/HistoryMessage" } }, "required": [ "success", "data" ] }, "OfficialServiceWindow": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "open", "closed", "unknown" ], "description": "`open`: the person messaged, reacted or called this Number through the Official API in the last 24 hours, so free-form messages can be sent. `closed`: no such activity in the last 24 hours; only approved templates can be sent, and Polymorfa refuses free-form sends with `conversation_window_closed`. `unknown`: Polymorfa cannot prove the window is closed; sends are passed to WhatsApp, which decides." }, "reason": { "type": "string", "nullable": true, "enum": [ "not_tracked", "tracking_started", "notifications_interrupted", "identity_unlinked", null ], "description": "Why the state is `unknown`, otherwise null. `not_tracked`: no WhatsApp notification has been processed for this connection yet. `tracking_started`: tracking began less than 24 hours ago. `notifications_interrupted`: a WhatsApp notification could not be processed in the last 24 hours. `identity_unlinked`: someone without a phone number (or username ID) wrote in during the last 24 hours and could be this person." }, "openedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the person's latest known message, reaction or call started or reset the window. Null when none is known." }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "`openedAt` plus 24 hours. In the past when the window has closed." }, "checkedAt": { "type": "string", "format": "date-time" } }, "required": [ "state", "reason", "openedAt", "expiresAt", "checkedAt" ] }, "GetCustomerServiceWindowResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialServiceWindow" } }, "required": [ "success", "data" ] }, "MetaPricingGroup": { "type": "object", "properties": { "category": { "type": "string", "description": "Pricing category as WhatsApp reported it, for example `marketing`, `utility`, `authentication` or `service`.", "example": "utility" }, "pricingModel": { "type": "string", "description": "Pricing model as WhatsApp reported it, for example `PMP`.", "example": "PMP" }, "pricingType": { "type": "string", "nullable": true, "description": "Pricing type as WhatsApp reported it, for example `regular`, `free_customer_service` or `free_entry_point`. Null when not reported.", "example": "regular" }, "billable": { "type": "boolean", "nullable": true, "description": "The `billable` flag as WhatsApp reported it. Null when not reported." }, "messages": { "type": "integer", "minimum": 0, "description": "Messages WhatsApp reported with this classification." } }, "required": [ "category", "pricingModel", "pricingType", "billable", "messages" ] }, "MetaPricingSummary": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "meta" ], "description": "Always `meta`: these are WhatsApp's own reports. Meta bills your WhatsApp Business Account directly. They are not a Polymorfa charge and contain no prices." }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "messages": { "type": "integer", "minimum": 0, "description": "Messages with a WhatsApp pricing report in the period." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/MetaPricingGroup" } } }, "required": [ "source", "since", "until", "messages", "groups" ] }, "GetMetaPricingSummaryResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MetaPricingSummary" } }, "required": [ "success", "data" ] }, "CallPermissionLimit": { "type": "object", "properties": { "period": { "type": "string", "description": "ISO 8601 duration of the window, for example `PT24H` or `P7D`." }, "maxAllowed": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "resetsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the window resets, when WhatsApp reports it." } }, "required": [ "period", "maxAllowed", "used", "resetsAt" ], "additionalProperties": false }, "CallPermissionAction": { "type": "object", "nullable": true, "properties": { "allowed": { "type": "boolean", "description": "Whether WhatsApp allows the action now." }, "limits": { "type": "array", "items": { "$ref": "#/components/schemas/CallPermissionLimit" } } }, "required": [ "allowed", "limits" ], "additionalProperties": false, "description": "Whether this number can send the person a call permission request now, with WhatsApp's limits." }, "CallPermission": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ConversationIdentity" }, "status": { "type": "string", "enum": [ "none", "temporary", "permanent", "revoked" ], "description": "`none`: no permission. `temporary`: granted until `expiresAt`. `permanent`: granted without expiry. `revoked`: the person declined or withdrew permission, or WhatsApp withdrew it after unanswered calls." }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When a temporary permission ends; null otherwise." }, "source": { "type": "string", "nullable": true, "enum": [ "user_action", "automatic", "sync", "call_refused", null ], "description": "How the last change was learned: the person's reply (`user_action`), WhatsApp acting on its own (`automatic`), asking WhatsApp (`sync`), or a call WhatsApp refused for lack of permission (`call_refused`). Null when nothing is recorded." }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the status last changed, or null." }, "checkedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When WhatsApp was last asked, or null." }, "fresh": { "type": "boolean", "description": "True when WhatsApp was asked during this request. False means the stored state is returned because WhatsApp could not be reached." }, "actions": { "type": "object", "nullable": true, "properties": { "requestPermission": { "$ref": "#/components/schemas/CallPermissionAction" }, "startCall": { "allOf": [ { "$ref": "#/components/schemas/CallPermissionAction" }, { "description": "Whether this number can call the person now, with WhatsApp's limits." } ] } }, "required": [ "requestPermission", "startCall" ], "additionalProperties": false, "description": "WhatsApp's limits, present when `fresh` is true." } }, "required": [ "conversation", "status", "expiresAt", "source", "updatedAt", "checkedAt", "fresh", "actions" ], "additionalProperties": false }, "GetCallPermissionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CallPermission" } }, "required": [ "success", "data" ] }, "CallCheck": { "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Whether a call placed now would pass every check Polymorfa and WhatsApp report." }, "refusal": { "type": "string", "nullable": true, "enum": [ "calls_disabled", "call_recipient_opted_out", "call_destination_blocked", "call_permission_required", "call_limit_reached", null ], "description": "The first reason the call would be refused, or null." }, "permission": { "type": "object", "nullable": true, "properties": { "status": { "type": "string", "enum": [ "none", "temporary", "permanent", "revoked" ], "description": "`none`: no permission. `temporary`: granted until `expiresAt`. `permanent`: granted without expiry. `revoked`: the person declined or withdrew permission, or WhatsApp withdrew it after unanswered calls." }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When a temporary permission ends; null otherwise." }, "source": { "type": "string", "nullable": true, "enum": [ "user_action", "automatic", "sync", "call_refused", null ], "description": "How the last change was learned: the person's reply (`user_action`), WhatsApp acting on its own (`automatic`), asking WhatsApp (`sync`), or a call WhatsApp refused for lack of permission (`call_refused`). Null when nothing is recorded." }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the status last changed, or null." }, "checkedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When WhatsApp was last asked, or null." }, "fresh": { "type": "boolean", "description": "True when WhatsApp was asked during this request. False means the stored state is returned because WhatsApp could not be reached." }, "actions": { "type": "object", "nullable": true, "properties": { "requestPermission": { "$ref": "#/components/schemas/CallPermissionAction" }, "startCall": { "allOf": [ { "$ref": "#/components/schemas/CallPermissionAction" }, { "description": "Whether this number can call the person now, with WhatsApp's limits." } ] } }, "required": [ "requestPermission", "startCall" ], "additionalProperties": false, "description": "WhatsApp's limits, present when `fresh` is true." } }, "required": [ "status", "expiresAt", "source", "updatedAt", "checkedAt", "fresh", "actions" ], "additionalProperties": false, "description": "The person's call permission on a Cloud API number; null on linked-device numbers." } }, "required": [ "allowed", "refusal", "permission" ], "additionalProperties": false }, "CheckCallResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CallCheck" } }, "required": [ "success", "data" ] }, "CallCheckRequest": { "type": "object", "properties": { "session": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The session (number) that would place the call." }, "to": { "type": "string", "minLength": 1, "maxLength": 64, "description": "User ID or phone number in E.164 format." } }, "required": [ "session", "to" ], "additionalProperties": false }, "VoipCreatedCallLink": { "type": "object", "properties": { "session": { "type": "string" }, "token": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "video": { "type": "boolean" } }, "required": [ "session", "token", "url", "video" ] }, "VoipCreatedCallLinkEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VoipCreatedCallLink" } }, "required": [ "success", "data" ] }, "VoipCreateCallLinkRequest": { "type": "object", "properties": { "session": { "type": "string", "minLength": 1, "maxLength": 128 }, "video": { "type": "boolean", "description": "Create a video link. Defaults to false (voice)." } }, "required": [ "session" ], "additionalProperties": false }, "VoipPreviewedCallLink": { "type": "object", "properties": { "session": { "type": "string" }, "video": { "type": "boolean" }, "creator": { "$ref": "#/components/schemas/ConversationIdentity" }, "approvalRequired": { "type": "boolean" }, "isAdmin": { "type": "boolean", "description": "Whether WhatsApp reports this Number as a link administrator. This field does not grant API permissions." } }, "required": [ "session", "video", "creator", "approvalRequired", "isAdmin" ] }, "VoipPreviewedCallLinkEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VoipPreviewedCallLink" } }, "required": [ "success", "data" ] }, "VoipPreviewCallLinkRequest": { "type": "object", "properties": { "session": { "type": "string", "minLength": 1, "maxLength": 128 }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$", "description": "Private token from the WhatsApp call link. Send it only in the request body." }, "video": { "type": "boolean", "description": "True for a video link, false for a voice link. Must match the link." } }, "required": [ "session", "token" ], "additionalProperties": false }, "ICEServer": { "type": "object", "properties": { "urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "username": { "type": "string" }, "credential": { "type": "string" } }, "required": [ "urls" ] }, "SDPAnswer": { "type": "object", "properties": { "sdp": { "type": "string" }, "iceServers": { "type": "array", "items": { "$ref": "#/components/schemas/ICEServer" } } }, "required": [ "sdp", "iceServers" ] }, "VoipOfferResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SDPAnswer" } }, "required": [ "success", "data" ] }, "VoipOfferRequest": { "type": "object", "properties": { "sdp": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } }, "required": [ "sdp", "connectionId" ] }, "VoipRenegotiateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SDPAnswer" } }, "required": [ "success", "data" ] }, "VoipRenegotiateRequest": { "type": "object", "properties": { "sdp": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } }, "required": [ "sdp", "connectionId" ] }, "VoipPlacedCall": { "type": "object", "properties": { "callId": { "type": "string" }, "session": { "type": "string" }, "video": { "type": "boolean" } }, "required": [ "callId", "session", "video" ] }, "VoipPlacedCallResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VoipPlacedCall" } }, "required": [ "success", "data" ] }, "VoipPlaceCallRequest": { "type": "object", "properties": { "session": { "type": "string", "minLength": 1, "example": "support" }, "to": { "type": "string", "pattern": "^(?:\\+[1-9]\\d{1,14}|[1-9][0-9]{0,18})$", "example": "+15550100" }, "groupId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "participants": { "type": "array", "items": { "type": "string", "pattern": "^(?:\\+[1-9]\\d{1,14}|[1-9][0-9]{0,18})$" }, "minItems": 2, "maxItems": 31, "uniqueItems": true }, "video": { "type": "boolean" }, "exclusive": { "type": "boolean", "description": "Claim the call for the placing participant." }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } }, "description": "Provide exactly one of to, participants or groupId. Group calls require a Linked Device number and 2 to 31 remote recipients.", "oneOf": [ { "required": [ "to" ], "not": { "anyOf": [ { "required": [ "participants" ] }, { "required": [ "groupId" ] } ] } }, { "required": [ "participants" ], "not": { "anyOf": [ { "required": [ "to" ] }, { "required": [ "groupId" ] } ] } }, { "required": [ "groupId" ], "not": { "anyOf": [ { "required": [ "to" ] }, { "required": [ "participants" ] } ] } } ] }, "VoipAnswerResult": { "type": "object", "properties": { "answered": { "type": "boolean" }, "answeredBy": { "type": "string", "example": "client:agent-7" }, "exclusive": { "type": "boolean" } }, "required": [ "answered", "answeredBy", "exclusive" ] }, "VoipAcceptCallResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VoipAnswerResult" } }, "required": [ "success", "data" ] }, "VoipAcceptCallRequest": { "type": "object", "properties": { "video": { "type": "boolean" }, "exclusive": { "type": "boolean", "description": "Claim the call. Other participants then receive `409 call_claimed` for accept and media, and their open connections close." }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } } }, "VoipRejectCallRequest": { "type": "object", "properties": { "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } } }, "VoipLeaveRequest": { "type": "object", "properties": { "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } }, "required": [ "connectionId" ] }, "VoipReactionRequest": { "type": "object", "properties": { "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call, which must own the connection. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" }, "emoji": { "type": "string", "enum": [ "", "👍", "❤️", "😂", "😮", "😢", "🙏" ], "description": "Empty clears the previous reaction." } }, "required": [ "connectionId", "emoji" ], "additionalProperties": false }, "VoipHandRequest": { "type": "object", "properties": { "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call, which must own the connection. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" }, "raised": { "type": "boolean" } }, "required": [ "connectionId", "raised" ], "additionalProperties": false }, "VoipAddParticipantRequest": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^(?:\\+[1-9]\\d{1,14}|[1-9][0-9]{0,18})$", "example": "+15550100" } }, "required": [ "to" ] }, "VoipParticipant": { "type": "object", "properties": { "handRaised": { "type": "boolean", "description": "Whether this participant has raised their hand." }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "bsuid": { "type": "string", "pattern": "^[A-Z]{2}\\.[A-Za-z0-9]{1,128}$" }, "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "audioMuted": { "type": "boolean" }, "video": { "type": "boolean" }, "state": { "type": "string", "enum": [ "invited", "ringing", "connected", "left" ] } }, "required": [ "id", "audioMuted", "video", "state" ], "additionalProperties": false }, "VoipAddParticipantResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VoipParticipant" } }, "required": [ "success", "data" ] }, "VoipCandidateRequest": { "type": "object", "properties": { "candidate": { "type": "string" }, "sdpMid": { "type": "string" }, "sdpMLineIndex": { "type": "integer" }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" } }, "required": [ "candidate", "connectionId" ] }, "TrickleCandidate": { "type": "object", "properties": { "candidate": { "type": "string" }, "sdpMid": { "type": "string" }, "sdpMLineIndex": { "type": "integer" } }, "required": [ "candidate" ] }, "VoipCandidatesResponse": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/TrickleCandidate" } } }, "required": [ "candidates" ] }, "VoipCandidatesEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VoipCandidatesResponse" } }, "required": [ "success", "data" ] }, "VoipCallReportClient": { "type": "object", "properties": { "sdk": { "type": "string", "pattern": "^[a-z0-9@/._-]{1,32}$", "description": "Package name of the SDK that sends the report.", "example": "@polymorfa/browser" }, "version": { "type": "string", "maxLength": 32, "pattern": "^[0-9]{1,6}\\.[0-9]{1,6}\\.[0-9]{1,6}(?:[-+][0-9A-Za-z.+-]{1,24})?$", "description": "SDK version: `MAJOR.MINOR.PATCH` with an optional suffix.", "example": "1.4.0" }, "platform": { "type": "string", "enum": [ "browser", "node", "other" ] } }, "required": [ "sdk", "version", "platform" ], "additionalProperties": false }, "VoipCallQuality": { "type": "object", "properties": { "rttMs": { "type": "integer", "minimum": 0, "maximum": 60000, "description": "Round-trip time in milliseconds.", "example": 84 }, "jitterMs": { "type": "integer", "minimum": 0, "maximum": 60000, "description": "Receive jitter in milliseconds.", "example": 6 }, "packetsLost": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Packets lost since the connection started.", "example": 12 }, "packetsReceived": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Packets received since the connection started.", "example": 4810 }, "audioCodec": { "type": "string", "pattern": "^[A-Za-z0-9/.-]{1,32}$", "description": "Negotiated audio codec.", "example": "audio/opus" }, "videoCodec": { "type": "string", "pattern": "^[A-Za-z0-9/.-]{1,32}$", "description": "Negotiated video codec.", "example": "video/VP8" }, "candidateType": { "type": "string", "enum": [ "host", "srflx", "prflx", "relay" ], "description": "Type of the local ICE candidate in use. `relay` means media flows through a TURN relay." }, "reconnects": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Times this connection reconnected so far.", "example": 0 } }, "additionalProperties": false, "description": "Omit figures you did not measure. Send at least one.", "minProperties": 1 }, "VoipCallQualityReport": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "quality" ] }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" }, "client": { "$ref": "#/components/schemas/VoipCallReportClient" }, "quality": { "$ref": "#/components/schemas/VoipCallQuality" } }, "required": [ "kind", "connectionId", "quality" ], "additionalProperties": false }, "VoipCallErrorReport": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "error" ] }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "Client-chosen identifier of one media connection. Reusing it replaces that connection.", "example": "conn_0123456789" }, "participant": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "Server credentials only: the participant acting in the call. Defaults to `default`. Client tokens act as their own participant and must omit this field.", "example": "agent-7" }, "client": { "$ref": "#/components/schemas/VoipCallReportClient" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "media_permission_denied", "device_not_found", "device_in_use", "ice_failed", "negotiation_failed", "media_timeout", "reconnect_exhausted", "token_refresh_failed", "unsupported_browser", "other" ] } }, "required": [ "code" ], "additionalProperties": false } }, "required": [ "kind", "connectionId", "error" ], "additionalProperties": false }, "VoipCallReportRequest": { "oneOf": [ { "$ref": "#/components/schemas/VoipCallQualityReport" }, { "$ref": "#/components/schemas/VoipCallErrorReport" } ], "discriminator": { "propertyName": "kind", "mapping": { "quality": "#/components/schemas/VoipCallQualityReport", "error": "#/components/schemas/VoipCallErrorReport" } } }, "RejectCallRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "ID of the incoming caller" } }, "required": [ "from" ] }, "Participant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" } }, "required": [ "id", "isAdmin", "isSuperAdmin" ] }, "Group": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa group ID. Keep it as a string." }, "name": { "type": "string" }, "description": { "type": "string" }, "ownerId": { "type": "string" }, "createdAt": { "type": "number", "description": "Unix timestamp in seconds" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } }, "required": [ "id", "name", "description", "ownerId", "createdAt", "participants" ] }, "ListGroupsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } }, "required": [ "success", "data" ] }, "CreateGroupResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Group" } }, "required": [ "success", "data" ] }, "CreateGroupRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "participants": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "minItems": 1 } }, "required": [ "name", "participants" ] }, "GroupInviteInfo": { "type": "object", "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "creatorId": { "type": "string" }, "createdAt": { "type": "number" }, "size": { "type": "number" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } }, "required": [ "id", "subject", "creatorId", "createdAt", "size", "participants" ] }, "GetGroupJoinInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/GroupInviteInfo" } }, "required": [ "success", "data" ] }, "JoinGroupRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 } }, "required": [ "code" ] }, "GetGroupResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Group" } }, "required": [ "success", "data" ] }, "SetGroupFieldRequest": { "type": "object", "properties": { "value": { "type": "string" } }, "required": [ "value" ] }, "InviteCodeResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Group invite code" } }, "required": [ "code" ] }, "GetGroupInviteCodeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/InviteCodeResponse" } }, "required": [ "success", "data" ] }, "RevokeGroupInviteCodeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/InviteCodeResponse" } }, "required": [ "success", "data" ] }, "GetGroupParticipantsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } }, "required": [ "success", "data" ] }, "GroupParticipantsRequest": { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "minItems": 1 } }, "required": [ "participants" ] }, "SetGroupPictureRequest": { "type": "object", "properties": { "url": { "type": "string" }, "base64": { "type": "string" } } }, "GroupAdminOnlySettingRequest": { "type": "object", "properties": { "adminsOnly": { "type": "boolean" } }, "required": [ "adminsOnly" ] }, "GroupMemberAddModeRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "admin_add", "all_member_add" ] } }, "required": [ "mode" ] }, "GroupJoinApprovalRequest": { "type": "object", "properties": { "required": { "type": "boolean" } }, "required": [ "required" ] }, "OfficialGroupSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "subject": { "type": "string" }, "createdAt": { "type": "string", "description": "Creation time as WhatsApp reported it." } }, "required": [ "id" ] }, "OfficialGroupCursors": { "type": "object", "properties": { "before": { "type": "string" }, "after": { "type": "string" } } }, "OfficialGroupList": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialGroupSummary" } }, "cursors": { "$ref": "#/components/schemas/OfficialGroupCursors" }, "hasMore": { "type": "boolean" } }, "required": [ "groups", "cursors", "hasMore" ] }, "ListOfficialGroupsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupList" } }, "required": [ "success", "data" ] }, "CreateOfficialGroupResult": { "type": "object", "properties": { "requestId": { "type": "string", "description": "WhatsApp creates the group asynchronously. A `group.update` event with action `created` (or `create_failed`) carries this request ID, the group's conversation ID and its invite link." } }, "required": [ "requestId" ] }, "CreateOfficialGroupResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CreateOfficialGroupResult" } }, "required": [ "success", "data" ] }, "CreateOfficialGroupRequest": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Group subject, 1 to 128 characters. Leading and trailing whitespace is removed." }, "description": { "type": "string", "maxLength": 2048, "description": "Group description, at most 2048 characters." }, "joinApprovalRequired": { "type": "boolean", "description": "When true, people who open the invite link send a join request that you approve or reject. Defaults to false: anyone with the link joins." } }, "required": [ "subject" ], "additionalProperties": false }, "OfficialGroup": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "subject": { "type": "string" }, "description": { "type": "string" }, "suspended": { "type": "boolean", "description": "True when WhatsApp suspended the group." }, "createdAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0, "description": "Participants, excluding your business." }, "joinApprovalRequired": { "type": "boolean" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationIdentity" } } }, "required": [ "id", "participants" ] }, "GetOfficialGroupResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroup" } }, "required": [ "success", "data" ] }, "OfficialGroupChangeAccepted": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ], "description": "WhatsApp accepted the request. Its outcome arrives as a `group.update` or `group.participant` event." } }, "required": [ "accepted" ] }, "UpdateOfficialGroupResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupChangeAccepted" } }, "required": [ "success", "data" ] }, "UpdateOfficialGroupRequest": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Group subject, 1 to 128 characters. Leading and trailing whitespace is removed." }, "description": { "type": "string", "maxLength": 2048, "description": "Group description, at most 2048 characters." } }, "additionalProperties": false }, "DeleteOfficialGroupResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupChangeAccepted" } }, "required": [ "success", "data" ] }, "OfficialGroupInviteLink": { "type": "object", "properties": { "inviteLink": { "type": "string", "format": "uri", "example": "https://chat.whatsapp.com/LINK_ID" } }, "required": [ "inviteLink" ] }, "GetOfficialGroupInviteLinkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupInviteLink" } }, "required": [ "success", "data" ] }, "ResetOfficialGroupInviteLinkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupInviteLink" } }, "required": [ "success", "data" ] }, "RemoveOfficialGroupParticipantsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupChangeAccepted" } }, "required": [ "success", "data" ] }, "RemoveOfficialGroupParticipantsRequest": { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 8, "description": "One to eight participants, each a conversation ID or an E.164 phone number. A removed participant cannot rejoin with the invite link." } }, "required": [ "participants" ], "additionalProperties": false }, "OfficialGroupJoinRequest": { "type": "object", "properties": { "joinRequestId": { "type": "string" }, "user": { "$ref": "#/components/schemas/ConversationIdentity" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "joinRequestId", "user" ] }, "OfficialGroupJoinRequestList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialGroupJoinRequest" } }, "cursors": { "$ref": "#/components/schemas/OfficialGroupCursors" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "cursors", "hasMore" ] }, "ListOfficialGroupJoinRequestsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupJoinRequestList" } }, "required": [ "success", "data" ] }, "OfficialGroupJoinRequestDecision": { "type": "object", "properties": { "succeeded": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "joinRequestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "title": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "joinRequestId", "errors" ] } } }, "required": [ "succeeded", "failed" ] }, "ApproveOfficialGroupJoinRequestsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupJoinRequestDecision" } }, "required": [ "success", "data" ] }, "OfficialGroupJoinRequestIds": { "type": "object", "properties": { "joinRequestIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_=-]{1,256}$" }, "minItems": 1, "maxItems": 1024, "description": "Join request IDs from the join request list or the `group.participant` event." } }, "required": [ "joinRequestIds" ], "additionalProperties": false }, "RejectOfficialGroupJoinRequestsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupJoinRequestDecision" } }, "required": [ "success", "data" ] }, "PinOfficialGroupMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OfficialGroupChangeAccepted" } }, "required": [ "success", "data" ] }, "PinOfficialGroupMessageRequest": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "pin" ] }, "messageId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "ID of a message in this group.", "example": "739182640518203" }, "expirationDays": { "type": "integer", "minimum": 1, "maximum": 30, "description": "How long the message stays pinned, 1 to 30 days." } }, "required": [ "operation", "messageId", "expirationDays" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "unpin" ] }, "messageId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "ID of a pinned message in this group.", "example": "739182640518203" } }, "required": [ "operation", "messageId" ], "additionalProperties": false } ] }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "pushName": { "type": "string" }, "businessName": { "type": "string" }, "profileUrl": { "type": "string" } }, "required": [ "id", "name", "pushName" ] }, "ListContactsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "success", "data" ] }, "CheckContactResult": { "type": "object", "properties": { "exists": { "type": "boolean" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" } }, "required": [ "exists" ] }, "CheckContactsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckContactResult" } } }, "required": [ "success", "data" ] }, "Blocklist": { "type": "object", "properties": { "hash": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id" ] } } }, "required": [ "hash", "contacts" ] }, "GetBlocklistResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Blocklist" } }, "required": [ "success", "data" ] }, "GetContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "success", "data" ] }, "ProfilePictureResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS URL of the profile picture" } }, "required": [ "url" ] }, "GetContactPictureResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProfilePictureResponse" } }, "required": [ "success", "data" ] }, "UserInfo": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "status": { "type": "string" }, "pictureId": { "type": "string" }, "verifiedName": { "type": "string" }, "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "device": { "type": "integer" } }, "required": [ "id", "device" ] } } }, "required": [ "id", "status", "pictureId", "verifiedName", "devices" ] }, "GetUserInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/UserInfo" } }, "required": [ "success", "data" ] }, "GetUserDevicesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" }, "device": { "type": "integer" } }, "required": [ "device" ] } } }, "required": [ "success", "data" ] }, "BusinessProfile": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "description": { "type": "string" }, "websites": { "type": "array", "items": { "type": "string", "format": "uri" } }, "coverPhotoId": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "options": { "type": "object", "additionalProperties": { "type": "string" } }, "hoursTimeZone": { "type": "string" }, "hours": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "string" }, "mode": { "type": "string" }, "openTime": { "type": "string" }, "closeTime": { "type": "string" } }, "required": [ "dayOfWeek", "mode", "openTime", "closeTime" ] } } }, "required": [ "id", "address", "email", "description", "websites", "coverPhotoId", "categories", "options", "hoursTimeZone", "hours" ] }, "GetBusinessProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessProfile" } }, "required": [ "success", "data" ] }, "BusinessLinkedAccounts": { "type": "object", "properties": { "facebookPage": { "type": "object", "properties": { "hasActiveCTWAAd": { "type": "boolean" }, "hasCreatedAd": { "type": "boolean" }, "id": { "type": "string" }, "displayName": { "type": "string" }, "profileSync": { "type": "string", "enum": [ "disable", "import" ] }, "profilePictureUrl": { "type": "string", "format": "uri" }, "showOnProfile": { "type": "boolean" }, "whatsAppAsPageButton": { "type": "boolean" } }, "required": [ "hasActiveCTWAAd", "hasCreatedAd", "id", "displayName", "profilePictureUrl", "showOnProfile", "whatsAppAsPageButton" ] }, "facebookBusiness": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "catalogId": { "type": "string" }, "catalogState": { "type": "string", "enum": [ "disable", "import" ] } }, "required": [ "id", "displayName" ] }, "instagramProfessional": { "type": "object", "properties": { "handle": { "type": "string" }, "displayName": { "type": "string" }, "profilePictureUrl": { "type": "string", "format": "uri" }, "showOnProfile": { "type": "boolean" } }, "required": [ "handle", "displayName", "profilePictureUrl", "showOnProfile" ] }, "whatsAppAdIdentity": { "type": "object", "properties": { "hasActiveCTWAAd": { "type": "boolean" }, "hasCreatedAd": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "hasActiveCTWAAd", "hasCreatedAd", "id" ] } } }, "GetBusinessLinkedAccountsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessLinkedAccounts" } }, "required": [ "success", "data" ] }, "BusinessEligibility": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "meta_verified", "marketing_messages", "genai", "genai_image", "meta_one", "bb_pro" ] }, "status": { "type": "string" }, "expiration": { "type": "integer" }, "additionalParams": { "type": "string" }, "showPrivacyInterstitialToNewUsers": { "type": "boolean" }, "v1Enabled": { "type": "boolean" } }, "required": [ "feature", "status" ] }, "maxItems": 6 } }, "required": [ "features" ] }, "GetBusinessEligibilityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessEligibility" } }, "required": [ "success", "data" ] }, "GetOwnBusinessProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessProfile" } }, "required": [ "success", "data" ] }, "UpdateBusinessProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "success", "data" ] }, "BusinessProfileUpdateRequest": { "type": "object", "properties": { "address": { "type": "string", "maxLength": 512 }, "email": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "maxLength": 320, "format": "email" } ] }, "description": { "type": "string", "maxLength": 1024 }, "websites": { "type": "array", "items": { "type": "string", "maxLength": 2048, "format": "uri" }, "minItems": 1, "maxItems": 2 }, "hours": { "type": "object", "properties": { "timeZone": { "type": "string", "minLength": 1, "maxLength": 128 }, "days": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat" ] }, "mode": { "type": "string", "enum": [ "specific_hours", "open_24h", "appointment_only" ] }, "openTime": { "type": "integer", "minimum": 0, "maximum": 1439 }, "closeTime": { "type": "integer", "minimum": 0, "maximum": 1439 } }, "required": [ "dayOfWeek", "mode" ] }, "minItems": 1, "maxItems": 7 } }, "required": [ "timeZone", "days" ] } } }, "SetBusinessCoverPhotoResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "coverPhotoId": { "type": "string" } }, "required": [ "coverPhotoId" ] } }, "required": [ "success", "data" ] }, "BusinessCoverPhotoRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "type": "string", "minLength": 1, "maxLength": 6990508 } } }, "DeleteBusinessCoverPhotoResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "success", "data" ] }, "BusinessMerchantCompliance": { "type": "object", "properties": { "entityName": { "type": "string", "maxLength": 256 }, "entityType": { "type": "string", "enum": [ "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "PRIVATE_COMPANY", "PUBLIC_COMPANY", "LIMITED_LIABILITY_PARTNERSHIP", "OTHER" ] }, "isRegistered": { "type": "boolean" }, "entityTypeCustom": { "type": "string", "maxLength": 256 }, "customerCare": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "landlineNumber": { "type": "string", "maxLength": 64 }, "mobileNumber": { "type": "string", "maxLength": 64 } }, "required": [ "email", "landlineNumber", "mobileNumber" ], "additionalProperties": false }, "grievanceOfficer": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "landlineNumber": { "type": "string", "maxLength": 64 }, "mobileNumber": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "maxLength": 256 } }, "required": [ "email", "landlineNumber", "mobileNumber", "name" ], "additionalProperties": false } }, "required": [ "entityName", "entityType", "isRegistered", "entityTypeCustom", "customerCare", "grievanceOfficer" ], "additionalProperties": false }, "GetBusinessMerchantComplianceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessMerchantCompliance" } }, "required": [ "success", "data" ] }, "SetBusinessMerchantComplianceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessMerchantCompliance" } }, "required": [ "success", "data" ] }, "BusinessQuickReplyMutation": { "type": "object", "properties": { "shortcut": { "type": "string", "minLength": 1, "maxLength": 25, "pattern": "^[\\p{L}\\p{N}]+$" }, "message": { "type": "string", "minLength": 1, "maxLength": 65536 }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 100, "default": [] }, "count": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 0 } }, "required": [ "shortcut", "message" ] }, "BusinessQuickReply": { "allOf": [ { "$ref": "#/components/schemas/BusinessQuickReplyMutation" }, { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } ] }, "CreateBusinessQuickReplyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessQuickReply" } }, "required": [ "success", "data" ] }, "BusinessQuickReplyObserved": { "allOf": [ { "$ref": "#/components/schemas/BusinessQuickReply" }, { "type": "object", "properties": { "associatedLabelIds": { "type": "array", "items": { "type": "string" } }, "observedAt": { "type": "string", "format": "date-time" } }, "required": [ "associatedLabelIds", "observedAt" ] } ] }, "BusinessQuickReplyCollection": { "type": "object", "properties": { "policy": { "type": "string", "enum": [ "off", "events", "cache" ] }, "status": { "type": "string", "enum": [ "disabled", "unknown", "partial", "fresh" ] }, "unknownReason": { "type": "string", "enum": [ "observation_disabled", "not_retained", "not_observed" ] }, "observedAt": { "type": "string", "format": "date-time" }, "quickReplies": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessQuickReplyObserved" } } }, "required": [ "policy", "status", "quickReplies" ] }, "ListBusinessQuickRepliesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessQuickReplyCollection" } }, "required": [ "success", "data" ] }, "SetBusinessQuickReplyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessQuickReply" } }, "required": [ "success", "data" ] }, "DeleteBusinessQuickReplyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "DELETED" ] } }, "required": [ "id", "status" ] } }, "required": [ "success", "data" ] }, "BusinessProduct": { "type": "object", "properties": { "id": { "type": "string" }, "retailerId": { "type": "string" }, "belongsTo": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "string" }, "currency": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "shimmedUrl": { "type": "string", "format": "uri" }, "hidden": { "type": "boolean" }, "sanctioned": { "type": "boolean" }, "maxAvailable": { "type": "integer", "minimum": 0 }, "availability": { "type": "string" }, "complianceCategory": { "type": "string" }, "compliance": { "type": "object", "properties": { "countryCodeOrigin": { "type": "string" }, "importerName": { "type": "string" }, "importerAddress": { "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "countryCode": { "type": "string" } } } } }, "media": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "originalUrl": { "type": "string", "format": "uri" }, "requestUrl": { "type": "string", "format": "uri" } }, "required": [ "id" ] } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "originalUrl": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" } }, "required": [ "id" ] } } }, "required": [ "images", "videos" ] }, "salePrice": { "type": "object", "properties": { "price": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" } }, "required": [ "price" ] }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "canAppeal": { "type": "boolean" } }, "required": [ "canAppeal" ] }, "variant": { "type": "object", "properties": { "availability": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "available": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "available", "options" ] } } }, "required": [ "listings" ] }, "listingDetails": { "type": "object", "properties": { "description": { "type": "string" }, "lowestPrice": { "type": "string" }, "multiPrice": { "type": "string" } } }, "types": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "thumbnail": { "type": "object", "properties": { "id": { "type": "string" }, "originalUrl": { "type": "string", "format": "uri" }, "requestUrl": { "type": "string", "format": "uri" }, "originalDimensions": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } } } }, "required": [ "originalDimensions" ] } }, "required": [ "value" ] } } }, "required": [ "name", "options" ] } }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "availability", "listingDetails", "types", "properties" ] } }, "required": [ "id", "name", "price", "currency", "hidden", "sanctioned", "media", "status" ] }, "BusinessCatalogPage": { "type": "object", "properties": { "next": { "type": "string" }, "previous": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessProduct" } } }, "required": [ "products" ] }, "GetBusinessCatalogResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessCatalogPage" } }, "required": [ "success", "data" ] }, "CreateBusinessCatalogResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "SetBusinessCartEnabledResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "BusinessCartSettingRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "GetBusinessProductResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessProduct" } }, "required": [ "success", "data" ] }, "CreateBusinessProductResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessProduct" } }, "required": [ "success", "data" ] }, "BusinessProductMutationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "maxLength": 4096 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "price": { "type": "string", "pattern": "^\\d{1,18}$" }, "salePrice": { "type": "string", "pattern": "^\\d{1,18}$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "retailerId": { "type": "string", "maxLength": 256 }, "hidden": { "type": "boolean" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 4096, "format": "uri", "description": "HTTPS image source fetched through Polymorfa's SSRF-safe downloader" }, "base64": { "type": "string", "minLength": 1, "maxLength": 22369624 }, "mediaUrl": { "type": "string", "maxLength": 4096, "format": "uri", "description": "Already-uploaded WhatsApp or Meta media URL reused without downloading" } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 }, "videoUrls": { "type": "array", "items": { "type": "string", "maxLength": 4096, "format": "uri" }, "maxItems": 10 }, "complianceCategory": { "type": "string", "maxLength": 128 }, "compliance": { "type": "object", "properties": { "countryCodeOrigin": { "type": "string", "maxLength": 3 }, "importerName": { "type": "string", "maxLength": 256 }, "importerAddress": { "type": "object", "properties": { "street1": { "type": "string", "maxLength": 512 }, "street2": { "type": "string", "maxLength": 512 }, "city": { "type": "string", "maxLength": 256 }, "region": { "type": "string", "maxLength": 256 }, "postalCode": { "type": "string", "maxLength": 64 }, "countryCode": { "type": "string", "maxLength": 3 } }, "additionalProperties": false } }, "additionalProperties": false }, "width": { "type": "integer", "minimum": 1, "maximum": 1024 }, "height": { "type": "integer", "minimum": 1, "maximum": 1024 } }, "required": [ "name", "images" ], "additionalProperties": false }, "UpdateBusinessProductResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessProduct" } }, "required": [ "success", "data" ] }, "DeleteBusinessProductResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deletedCount": { "type": "integer", "minimum": 0 } }, "required": [ "deletedCount" ] } }, "required": [ "success", "data" ] }, "SetBusinessProductVisibilityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "BusinessProductVisibilityRequest": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "required": [ "hidden" ], "additionalProperties": false }, "AppealBusinessProductResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "BusinessCatalogAppealRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "reason" ], "additionalProperties": false }, "BusinessCollection": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessProduct" } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "canAppeal": { "type": "boolean" }, "commerceUrl": { "type": "string", "format": "uri" }, "rejectReason": { "type": "string" } }, "required": [ "canAppeal" ] } }, "required": [ "id", "name", "products", "status" ] }, "BusinessCollectionPage": { "type": "object", "properties": { "next": { "type": "string" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCollection" } } }, "required": [ "collections" ] }, "GetBusinessCollectionsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessCollectionPage" } }, "required": [ "success", "data" ] }, "CreateBusinessCollectionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "reviewStatus": { "type": "string" } }, "required": [ "id", "reviewStatus" ] } }, "required": [ "success", "data" ] }, "BusinessCollectionCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "productIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 1, "maxItems": 100 } }, "required": [ "name", "productIds" ], "additionalProperties": false }, "GetBusinessCollectionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessCollection" } }, "required": [ "success", "data" ] }, "ReorderBusinessCollectionsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "BusinessCollectionReorderRequest": { "type": "object", "properties": { "moves": { "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "fromIndex": { "type": "integer", "minimum": 0, "maximum": 99 }, "toIndex": { "type": "integer", "minimum": 0, "maximum": 99 } }, "required": [ "collectionId", "fromIndex", "toIndex" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "moves" ], "additionalProperties": false }, "UpdateBusinessCollectionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "reviewStatus": { "type": "string" } }, "required": [ "id", "reviewStatus" ] } }, "required": [ "success", "data" ] }, "BusinessCollectionUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "addProductIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 0, "maxItems": 100 }, "removeProductIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 0, "maxItems": 100 } }, "additionalProperties": false }, "DeleteBusinessCollectionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "AppealBusinessCollectionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } }, "required": [ "success", "data" ] }, "BusinessOrder": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0 }, "catalogId": { "type": "string" }, "price": { "type": "object", "properties": { "subtotal": { "type": "string" }, "total": { "type": "string" }, "currency": { "type": "string" }, "priceStatus": { "type": "string" } }, "required": [ "subtotal", "total", "currency" ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "imageId": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" }, "price": { "type": "string" }, "currency": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 }, "variantProperties": { "type": "string" } }, "required": [ "id", "price", "currency", "name", "quantity" ] } } }, "required": [ "id", "createdAt", "price", "products" ] }, "GetBusinessOrderResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/BusinessOrder" } }, "required": [ "success", "data" ] }, "BusinessOrderLookupRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 8192 } }, "required": [ "token" ] }, "ResolveIdentityResult": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "phoneNumber": { "type": "string" }, "bsuid": { "type": "string" }, "username": { "type": "string" }, "keyRequired": { "type": "boolean" } } }, "ResolveIdentityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ResolveIdentityResult" } }, "required": [ "success", "data" ] }, "UserSecurityCode": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "phoneNumber": { "type": "string" }, "username": { "type": "string" }, "numericCode": { "type": "string", "pattern": "^\\d{60}$" }, "qrCode": { "type": "string" } }, "required": [ "id", "numericCode", "qrCode" ] }, "UserSecurityCodeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/UserSecurityCode" } }, "required": [ "success", "data" ] }, "Channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "profileUrl": { "type": "string" }, "followers": { "type": "number" }, "muted": { "type": "boolean" }, "preview": { "type": "boolean" } } }, "ListChannelsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } }, "required": [ "success", "data" ] }, "CreateChannelResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Channel" } }, "required": [ "success", "data" ] }, "CreateChannelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "name" ] }, "GetChannelResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Channel" } }, "required": [ "success", "data" ] }, "ChannelMessage": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Channel ordering position. Use this value for before and after pagination cursors, not as a message ID." }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "whatsapp_ids": { "$ref": "#/components/schemas/WhatsAppMessageIds" }, "whatsapp_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", "deprecated": true }, "conversation": { "$ref": "#/components/schemas/ConversationIdentity" }, "type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "views": { "type": "integer", "minimum": 0 }, "reactionCounts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "text": { "type": "string" } }, "required": [ "position", "id", "whatsapp_ids", "conversation", "type", "timestamp", "views", "reactionCounts" ] }, "ListChannelMessagesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessage" } } }, "required": [ "success", "data" ] }, "ListChannelMessageUpdatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessage" } } }, "required": [ "success", "data" ] }, "ChannelReactionRequest": { "type": "object", "properties": { "reaction": { "type": "string", "maxLength": 32 } }, "required": [ "reaction" ] }, "ChannelLiveUpdates": { "type": "object", "properties": { "durationSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "durationSeconds" ] }, "ChannelLiveUpdatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ChannelLiveUpdates" } }, "required": [ "success", "data" ] }, "DeleteChannelResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "DELETED" ] } }, "required": [ "status" ] } }, "required": [ "success", "data" ] }, "SetPresenceRequest": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "available", "unavailable" ] } }, "required": [ "presence" ] }, "PresenceData": { "type": "object", "properties": { "desired": { "type": "string", "enum": [ "available", "unavailable" ] }, "desiredAt": { "type": "string", "format": "date-time" }, "lastSent": { "type": "string", "enum": [ "available", "unavailable" ] }, "lastSentAt": { "type": "string", "format": "date-time" }, "authoritative": { "type": "boolean", "enum": [ false ] } }, "required": [ "authoritative" ] }, "GetPresenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PresenceData" } }, "required": [ "success", "data" ] }, "ChatPresenceData": { "type": "object", "properties": { "policy": { "type": "string", "enum": [ "off", "events", "cache" ] }, "status": { "type": "string", "enum": [ "unknown", "fresh", "stale" ] }, "unknownReason": { "type": "string", "enum": [ "disabled", "not_observed", "suspended" ] }, "available": { "type": "boolean" }, "lastSeen": { "type": "string", "format": "date-time" }, "observedAt": { "type": "string", "format": "date-time" }, "subscriptionExpiresAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" }, "typingPolicy": { "type": "string", "enum": [ "off", "events", "cache" ] }, "typingStatus": { "type": "string", "enum": [ "unknown", "fresh", "stale" ] }, "typingUnknownReason": { "type": "string", "enum": [ "disabled", "not_observed", "suspended" ] }, "chatState": { "type": "object", "properties": { "sender": { "type": "string" }, "state": { "type": "string", "enum": [ "composing", "paused" ] }, "media": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } }, "required": [ "sender", "state", "observedAt", "stale" ] } }, "required": [ "policy", "status", "stale", "typingPolicy", "typingStatus" ] }, "GetChatPresenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ChatPresenceData" } }, "required": [ "success", "data" ] }, "PresenceSubscriptionData": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SUBSCRIBED" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "expiresAt" ] }, "SubscribePresenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PresenceSubscriptionData" } }, "required": [ "success", "data" ] }, "ProjectSafeMode": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "ceiling": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "dark", "online_while_sending", "online_hours" ] }, "typing": { "type": "string", "enum": [ "off", "before_text", "before_all" ] }, "reads": { "type": "string", "enum": [ "off", "replied_chats", "all_inbound" ] }, "pacing": { "type": "string", "enum": [ "off", "jittered", "conversation" ] }, "onlineStart": { "type": "integer", "minimum": 0, "maximum": 23 }, "onlineEnd": { "type": "integer", "minimum": 0, "maximum": 23 } }, "required": [ "presence", "typing", "reads", "pacing", "onlineStart", "onlineEnd" ] }, "entitled": { "type": "boolean" }, "entitlementReason": { "type": "string", "nullable": true } }, "required": [ "projectId", "ceiling", "entitled", "entitlementReason" ] }, "GetProjectSafeModeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectSafeMode" } }, "required": [ "success", "data" ] }, "UpdateProjectSafeModeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectSafeMode" } }, "required": [ "success", "data" ] }, "SessionSafeMode": { "type": "object", "properties": { "session": { "type": "string" }, "projectId": { "type": "string", "format": "uuid" }, "project": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "dark", "online_while_sending", "online_hours" ] }, "typing": { "type": "string", "enum": [ "off", "before_text", "before_all" ] }, "reads": { "type": "string", "enum": [ "off", "replied_chats", "all_inbound" ] }, "pacing": { "type": "string", "enum": [ "off", "jittered", "conversation" ] }, "onlineStart": { "type": "integer", "minimum": 0, "maximum": 23 }, "onlineEnd": { "type": "integer", "minimum": 0, "maximum": 23 } }, "required": [ "presence", "typing", "reads", "pacing", "onlineStart", "onlineEnd" ] }, "override": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "inherit", "dark", "online_while_sending", "online_hours" ] }, "typing": { "type": "string", "enum": [ "inherit", "off", "before_text", "before_all" ] }, "reads": { "type": "string", "enum": [ "inherit", "off", "replied_chats", "all_inbound" ] }, "pacing": { "type": "string", "enum": [ "inherit", "off", "jittered", "conversation" ] } }, "required": [ "presence", "typing", "reads", "pacing" ] }, "effective": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "dark", "online_while_sending", "online_hours" ] }, "typing": { "type": "string", "enum": [ "off", "before_text", "before_all" ] }, "reads": { "type": "string", "enum": [ "off", "replied_chats", "all_inbound" ] }, "pacing": { "type": "string", "enum": [ "off", "jittered", "conversation" ] }, "onlineStart": { "type": "integer", "minimum": 0, "maximum": 23 }, "onlineEnd": { "type": "integer", "minimum": 0, "maximum": 23 } }, "required": [ "presence", "typing", "reads", "pacing", "onlineStart", "onlineEnd" ] }, "applied": { "type": "object", "nullable": true, "properties": { "observedAt": { "type": "string" }, "presence": { "type": "string", "nullable": true }, "typing": { "type": "string", "nullable": true }, "reads": { "type": "string", "nullable": true }, "pacing": { "type": "string", "nullable": true } }, "required": [ "observedAt", "presence", "typing", "reads", "pacing" ] }, "mismatch": { "type": "boolean" }, "entitled": { "type": "boolean" }, "entitlementReason": { "type": "string", "nullable": true } }, "required": [ "session", "projectId", "project", "override", "effective", "applied", "mismatch", "entitled", "entitlementReason" ] }, "GetSessionSafeModeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SessionSafeMode" } }, "required": [ "success", "data" ] }, "UpdateSessionSafeModeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SessionSafeMode" } }, "required": [ "success", "data" ] }, "ProjectWarmupPlan": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "plan": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "warmupDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "dailyStart": { "type": "integer", "minimum": 1, "maximum": 2000 } }, "required": [ "enabled", "warmupDays", "dailyStart" ] }, "ceiling": { "type": "integer", "minimum": 1 }, "curve": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 0 }, "allowance": { "type": "integer", "minimum": 0 } }, "required": [ "day", "allowance" ] }, "maxItems": 91 }, "entitled": { "type": "boolean" }, "entitlementReason": { "type": "string", "nullable": true } }, "required": [ "projectId", "plan", "ceiling", "curve", "entitled", "entitlementReason" ] }, "GetProjectWarmupPlanResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectWarmupPlan" } }, "required": [ "success", "data" ] }, "UpdateProjectWarmupPlanResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectWarmupPlan" } }, "required": [ "success", "data" ] }, "ProjectHealthPolicy": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0 }, "enabled": { "type": "boolean" }, "threshold": { "type": "integer", "minimum": 0, "maximum": 100 }, "sessionAction": { "type": "string", "enum": [ "none", "stop", "slow_down", "log_out" ] }, "slowDownMps": { "type": "number", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "emailNotification": { "type": "boolean" }, "webhookNotification": { "type": "boolean" }, "integrations": { "type": "object", "properties": { "emailConfigured": { "type": "boolean" }, "webhookConfigured": { "type": "boolean" } }, "required": [ "emailConfigured", "webhookConfigured" ] } }, "required": [ "projectId", "version", "enabled", "threshold", "sessionAction", "slowDownMps", "emailNotification", "webhookNotification", "integrations" ] }, "GetProjectHealthPolicyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectHealthPolicy" } }, "required": [ "success", "data" ] }, "UpdateProjectHealthPolicyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectHealthPolicy" } }, "required": [ "success", "data" ] }, "UpdateProjectHealthPolicyInput": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0 }, "enabled": { "type": "boolean" }, "threshold": { "type": "integer", "minimum": 0, "maximum": 100 }, "sessionAction": { "type": "string", "enum": [ "none", "stop", "slow_down", "log_out" ] }, "slowDownMps": { "type": "number", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "emailNotification": { "type": "boolean" }, "webhookNotification": { "type": "boolean" } }, "required": [ "version", "enabled", "threshold", "sessionAction", "slowDownMps", "emailNotification", "webhookNotification" ], "additionalProperties": false }, "ProjectInsuranceEvidence": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "banInsuranceIncluded": { "type": "boolean" } }, "required": [ "projectId", "enabled", "banInsuranceIncluded" ] }, "GetProjectInsuranceEvidenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectInsuranceEvidence" } }, "required": [ "success", "data" ] }, "UpdateProjectInsuranceEvidenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectInsuranceEvidence" } }, "required": [ "success", "data" ] }, "ProjectObservationPolicy": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "presenceMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "typingMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "labelMode": { "type": "string", "enum": [ "off", "events", "cache", "project" ] }, "quickReplyMode": { "type": "string", "enum": [ "off", "events", "cache" ] } }, "required": [ "projectId", "presenceMode", "typingMode", "labelMode", "quickReplyMode" ] }, "GetProjectObservationPolicyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProjectObservationPolicy" } }, "required": [ "success", "data" ] }, "SessionObservationPolicy": { "type": "object", "properties": { "sessionName": { "type": "string" }, "projectId": { "type": "string", "format": "uuid" }, "project": { "type": "object", "properties": { "presenceMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "typingMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "labelMode": { "type": "string", "enum": [ "off", "events", "cache", "project" ] }, "quickReplyMode": { "type": "string", "enum": [ "off", "events", "cache" ] } }, "required": [ "presenceMode", "typingMode", "labelMode", "quickReplyMode" ] }, "override": { "type": "object", "properties": { "presenceMode": { "type": "string", "enum": [ "inherit", "off", "events", "cache" ] }, "typingMode": { "type": "string", "enum": [ "inherit", "off", "events", "cache" ] }, "labelMode": { "type": "string", "enum": [ "inherit", "off", "events", "cache", "project" ] }, "quickReplyMode": { "type": "string", "enum": [ "inherit", "off", "events", "cache" ] } }, "required": [ "presenceMode", "typingMode", "labelMode", "quickReplyMode" ] }, "effective": { "type": "object", "properties": { "presenceMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "typingMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "labelMode": { "type": "string", "enum": [ "off", "events", "cache", "project" ] }, "quickReplyMode": { "type": "string", "enum": [ "off", "events", "cache" ] } }, "required": [ "presenceMode", "typingMode", "labelMode", "quickReplyMode" ] } }, "required": [ "sessionName", "projectId", "project", "override", "effective" ] }, "GetSessionObservationPolicyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SessionObservationPolicy" } }, "required": [ "success", "data" ] }, "ProfileData": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "profilePicUrl": { "type": "string" }, "phonePlatform": { "type": "string", "enum": [ "android", "ios", "meta_cloud", "unknown" ], "description": "Where the account's primary WhatsApp client runs.", "x-enumDescriptions": { "android": "WhatsApp or WhatsApp Business on an Android phone.", "ios": "WhatsApp or WhatsApp Business on an iPhone.", "meta_cloud": "Meta hosts the number through Cloud API.", "unknown": "The phone has not reported a recognized platform." } }, "accountType": { "type": "string", "enum": [ "whatsapp_app", "business_app", "meta_cloud", "meta_coexistence" ], "description": "How the account uses WhatsApp.", "x-enumDescriptions": { "whatsapp_app": "WhatsApp app, connected as a linked device.", "business_app": "WhatsApp Business app, connected as a linked device.", "meta_cloud": "Meta Cloud API.", "meta_coexistence": "Meta Cloud API, with the WhatsApp Business app still active on the phone." } } }, "required": [ "name", "status" ] }, "GetProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProfileData" } }, "required": [ "success", "data" ] }, "SetProfileNameRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "SetProfileStatusRequest": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "SetProfilePictureRequest": { "type": "object", "properties": { "url": { "type": "string" }, "base64": { "type": "string" } } }, "PrivacySettings": { "type": "object", "properties": { "groupAdd": { "type": "string" }, "lastSeen": { "type": "string" }, "status": { "type": "string" }, "profile": { "type": "string" }, "readReceipts": { "type": "string" }, "online": { "type": "string" }, "callAdd": { "type": "string" }, "messages": { "type": "string" }, "defense": { "type": "string" }, "stickers": { "type": "string" } }, "required": [ "groupAdd", "lastSeen", "status", "profile", "readReceipts", "online", "callAdd", "messages", "defense", "stickers" ] }, "PrivacySettingsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PrivacySettings" } }, "required": [ "success", "data" ] }, "DefaultDisappearingTimerRequest": { "type": "object", "properties": { "durationSeconds": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 86400 ] }, { "type": "number", "enum": [ 604800 ] }, { "type": "number", "enum": [ 7776000 ] } ] } }, "required": [ "durationSeconds" ] }, "UpdatedPrivacySettingsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PrivacySettings" } }, "required": [ "success", "data" ] }, "SetPrivacySettingRequest": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "all", "contacts", "contact_allowlist", "contact_blacklist", "match_last_seen", "known", "none", "on_standard", "off" ] } }, "required": [ "value" ] }, "Label": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "integer" }, "orderIndex": { "type": "integer" }, "chatCount": { "type": "integer" }, "observedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "color" ] }, "LabelCollection": { "type": "object", "properties": { "policy": { "type": "string", "enum": [ "off", "events", "cache", "project" ] }, "status": { "type": "string", "enum": [ "disabled", "unknown", "partial", "fresh" ] }, "unknownReason": { "type": "string", "enum": [ "observation_disabled", "not_retained", "not_observed", "expired" ] }, "observedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } } }, "required": [ "policy", "status", "labels" ] }, "LabelReadData": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, { "$ref": "#/components/schemas/LabelCollection" } ] }, "ListLabelsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/LabelReadData" } }, "required": [ "success", "data" ] }, "CreateLabelResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Label" } }, "required": [ "success", "data" ] }, "CreateLabelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "integer", "minimum": 0, "maximum": 19 } }, "required": [ "name" ] }, "UpdateLabelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "integer", "minimum": 0, "maximum": 19 } } }, "GetChatLabelsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/LabelReadData" } }, "required": [ "success", "data" ] }, "SetChatLabelsRequest": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 20 } }, "required": [ "labels" ] }, "RetryConfig": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0 }, "delaySeconds": { "type": "integer", "minimum": 0 }, "policy": { "type": "string", "description": "linear, exponential, or constant" } }, "required": [ "attempts", "delaySeconds", "policy" ] }, "WebhookHeader": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "session": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "retries": { "$ref": "#/components/schemas/RetryConfig" }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookHeader" } }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "native", "meta" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "tenantId", "url", "events", "retries", "headers", "enabled", "createdAt" ] }, "ListWebhooksResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "success", "data" ] }, "CreateWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "success", "data" ] }, "CreateWebhookRequest": { "type": "object", "properties": { "session": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "hmacKey": { "type": "string" }, "retries": { "$ref": "#/components/schemas/RetryConfig" }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookHeader" } }, "format": { "type": "string", "enum": [ "native", "meta" ], "description": "\"native\" (default) = Polymorfa event envelope. \"meta\" = Meta Cloud API webhook shape (object/entry/changes/value), signed with X-Hub-Signature-256." } }, "required": [ "url" ] }, "GetWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "success", "data" ] }, "UpdateWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "success", "data" ] }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "hmacKey": { "type": "string" }, "retries": { "$ref": "#/components/schemas/RetryConfig" }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookHeader" } }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "native", "meta" ] } } }, "MediaInfo": { "type": "object", "properties": { "id": { "type": "string" }, "session": { "type": "string" }, "messageId": { "type": "string" }, "mimeType": { "type": "string" }, "fileLength": { "type": "integer", "minimum": 0 }, "persisted": { "type": "boolean" }, "s3Url": { "type": "string" } }, "required": [ "id", "session", "messageId", "mimeType", "fileLength", "persisted" ] }, "GetMediaInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MediaInfo" } }, "required": [ "success", "data" ] }, "WaTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "session": { "type": "string" }, "wabaId": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "PAUSED", "DISABLED", "DELETED", "ARCHIVED", "IN_APPEAL", "LIMIT_EXCEEDED", "PENDING_DELETION" ] }, "components": { "type": "array", "items": {} }, "metaTemplateId": { "type": "string" }, "rejectionReason": { "type": "string" }, "qualityScore": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tenantId", "session", "wabaId", "name", "language", "category", "status", "components", "createdAt", "updatedAt" ] }, "ListTemplatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WaTemplate" } } }, "required": [ "success", "data" ] }, "GetTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/WaTemplate" } }, "required": [ "success", "data" ] }, "EditTemplateAcceptedResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ] }, "name": { "type": "string" }, "language": { "type": "string" } }, "required": [ "accepted", "name", "language" ] } }, "required": [ "success", "data" ] }, "EditTemplateRequest": { "type": "object", "properties": { "components": { "type": "array", "items": {}, "minItems": 1 } }, "required": [ "components" ], "additionalProperties": false }, "CreateTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/WaTemplate" } }, "required": [ "success", "data" ] }, "CreateTemplateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" }, "language": { "type": "string", "minLength": 2 }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "components": { "type": "array", "items": {}, "minItems": 1 } }, "required": [ "name", "language", "category", "components" ] }, "MessageTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "language": { "type": "string" }, "status": { "type": "string" }, "kind": { "type": "string" }, "definition": {}, "sampleValues": {}, "cloudLinks": { "type": "array", "items": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "category", "language", "status", "kind", "cloudLinks", "createdAt", "updatedAt" ] }, "ListProjectTemplatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageTemplate" } } }, "required": [ "success", "data" ] }, "GetProjectTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MessageTemplate" } }, "required": [ "success", "data" ] }, "CreateProjectTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MessageTemplate" } }, "required": [ "success", "data" ] }, "CreateMessageTemplateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" }, "definition": { "type": "object", "additionalProperties": {} }, "sampleValues": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "name", "definition" ] }, "UpdateProjectTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MessageTemplate" } }, "required": [ "success", "data" ] }, "UpdateMessageTemplateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "definition": { "type": "object", "additionalProperties": {} }, "sampleValues": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PreviewProjectTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "success", "data" ] }, "PreviewMessageTemplateRequest": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string" } }, "surface": { "type": "string", "enum": [ "cloud", "whatsmeow", "sandbox" ] } } }, "TemplateSubmission": { "type": "object", "properties": { "session": { "type": "string", "description": "Number the template was submitted for." }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED" ], "description": "PENDING: sent to Meta for review. APPROVED: the number sends this template without Meta review." }, "autoApproved": { "type": "boolean", "description": "True when the number does not need Meta approval (any number that is not a Cloud API number). Nothing was sent to Meta." }, "metaTemplateId": { "type": "string", "nullable": true, "description": "Meta's template ID; null when auto-approved." } }, "required": [ "session", "status", "autoApproved", "metaTemplateId" ] }, "SubmitProjectTemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/MessageTemplate" }, { "type": "object", "properties": { "submission": { "$ref": "#/components/schemas/TemplateSubmission" } }, "required": [ "submission" ] } ] } }, "required": [ "success", "data" ] }, "SubmitMessageTemplateRequest": { "type": "object", "properties": { "session": { "type": "string", "minLength": 1 } }, "required": [ "session" ] }, "CampaignSendWindowRange": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local start time, `HH:MM` in 24-hour time, inclusive.", "example": "09:00" }, "end": { "type": "string", "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$", "description": "Local end time, `HH:MM` in 24-hour time or `24:00`, exclusive. Must be later than `start`.", "example": "18:00" } }, "required": [ "start", "end" ], "additionalProperties": false }, "CampaignSendWindow": { "type": "object", "nullable": true, "properties": { "timeZone": { "type": "string", "description": "IANA time zone the window is written in.", "example": "America/Sao_Paulo" }, "days": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "minItems": 1, "maxItems": 7, "description": "Weekdays the campaign may send on, in the window's time zone. At least one; no repeats.", "uniqueItems": true, "example": [ "monday", "tuesday", "wednesday", "thursday", "friday" ] }, "hours": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignSendWindowRange" }, "minItems": 1, "maxItems": 4, "description": "Local time ranges the campaign may send in on those days, at most 4. Ranges must not overlap. A range cannot cross midnight; use two ranges instead." }, "recipientTimeZone": { "type": "boolean", "description": "Evaluate the window in each recipient's own time zone. The zone comes from the recipient variable named by `timeZoneVariable` when it holds a valid IANA zone, otherwise from the phone number's country when that country uses one UTC offset, otherwise `timeZone`." }, "timeZoneVariable": { "type": "string", "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$", "description": "Recipient variable holding the recipient's IANA time zone, used when `recipientTimeZone` is true.", "example": "timeZone" } }, "required": [ "timeZone", "days", "hours", "recipientTimeZone", "timeZoneVariable" ], "description": "When the campaign may send; null sends at any time." }, "Campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "templateId": { "type": "string", "nullable": true }, "recipientListId": { "type": "string", "nullable": true }, "recipientCount": { "type": "number" }, "sentCount": { "type": "number" }, "deliveredCount": { "type": "number" }, "readCount": { "type": "number" }, "failedCount": { "type": "number" }, "skippedCount": { "type": "number" }, "scheduledAt": { "type": "number", "nullable": true }, "launchedAt": { "type": "number", "nullable": true }, "completedAt": { "type": "number", "nullable": true }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "sendWindow": { "$ref": "#/components/schemas/CampaignSendWindow" } }, "required": [ "id", "name", "status", "templateId", "recipientListId", "recipientCount", "sentCount", "deliveredCount", "readCount", "failedCount", "skippedCount", "scheduledAt", "launchedAt", "completedAt", "createdAt", "updatedAt", "sendWindow" ] }, "ListCampaignsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } } }, "required": [ "success", "data" ] }, "GetCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } }, "required": [ "success", "data" ] }, "CampaignAnalyticsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "success", "data" ] }, "CreateCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } }, "required": [ "success", "data" ] }, "CampaignSendWindowRequest": { "type": "object", "nullable": true, "properties": { "timeZone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "IANA time zone the window is written in, such as `America/Sao_Paulo`. When omitted, the team's time zone is stored, or `UTC` when the team has none.", "example": "America/Sao_Paulo" }, "days": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "minItems": 1, "maxItems": 7, "description": "Weekdays the campaign may send on, in the window's time zone. At least one; no repeats.", "uniqueItems": true, "example": [ "monday", "tuesday", "wednesday", "thursday", "friday" ] }, "hours": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignSendWindowRange" }, "minItems": 1, "maxItems": 4, "description": "Local time ranges the campaign may send in on those days, at most 4. Ranges must not overlap. A range cannot cross midnight; use two ranges instead." }, "recipientTimeZone": { "type": "boolean", "default": false, "description": "Evaluate the window in each recipient's own time zone. The zone comes from the recipient variable named by `timeZoneVariable` when it holds a valid IANA zone, otherwise from the phone number's country when that country uses one UTC offset, otherwise `timeZone`." }, "timeZoneVariable": { "type": "string", "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$", "default": "timeZone", "description": "Recipient variable holding the recipient's IANA time zone, used when `recipientTimeZone` is true.", "example": "timeZone" } }, "required": [ "days", "hours" ], "additionalProperties": false, "description": "When the campaign may send. Recipients outside the window stay `queued` and are sent when it next opens. `null` sends at any time." }, "CampaignRecipientInput": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Phone number in international format, for example `+14155550100`. Spaces, dots, hyphens and parentheses are ignored; a leading `00` is read as `+`." }, "variables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Template variables for this recipient. At most 50; names use letters, digits, `_`, `.` or `-`; values are stored as strings of at most 1,024 characters." } }, "required": [ "phone" ] }, "CreateCampaignRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "templateId": { "type": "string" }, "recipientListId": { "type": "string" }, "senderConfig": { "type": "object", "additionalProperties": {} }, "scheduledAt": { "type": "number" }, "sendWindow": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignSendWindowRequest" } ] }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRecipientInput" }, "maxItems": 1000, "description": "Recipients to add inline, at most 1,000. Every entry must be valid or the campaign is not created; a repeated phone is kept once. Combine with `recipientListId` to add an audience at launch; add more with the add-recipients endpoint while the campaign is a draft." } }, "required": [ "name" ] }, "UpdateCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } }, "required": [ "success", "data" ] }, "UpdateCampaignRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New name, 1 to 200 characters after trimming." }, "recipientListId": { "type": "string", "nullable": true, "format": "uuid", "description": "Audience to send to, or null for none. Only an unlaunched draft can change it; the campaign's current recipients are replaced by the audience's members at launch." }, "senderConfig": { "type": "object", "additionalProperties": {}, "description": "Replaces the sender selection and throughput. On an unlaunched draft it passes the same checks as create. Once the campaign has launched it must pass the launch checks." }, "scheduledAt": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 8640000000000000, "description": "Start time in milliseconds since the Unix epoch, or null to start at launch. Only an unlaunched draft can change it." }, "sendWindow": { "allOf": [ { "$ref": "#/components/schemas/CampaignSendWindowRequest" }, { "description": "When the campaign may send. Null removes the window. Only a draft or paused campaign can change it; a paused edit requires in-flight sends to have settled." } ], "nullable": true } }, "additionalProperties": false, "minProperties": 1 }, "CampaignOperation": { "allOf": [ { "$ref": "#/components/schemas/Campaign" }, { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid" } }, "required": [ "operationId" ] } ] }, "LaunchCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignOperation" } }, "required": [ "success", "data" ] }, "LaunchCampaignRequest": { "type": "object", "properties": { "scheduledAt": { "type": "number" } } }, "PauseCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignOperation" } }, "required": [ "success", "data" ] }, "ResumeCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignOperation" } }, "required": [ "success", "data" ] }, "CampaignStopOperation": { "allOf": [ { "$ref": "#/components/schemas/Campaign" }, { "type": "object", "properties": { "operationId": { "type": "string", "nullable": true, "format": "uuid", "description": "The operation that stops the campaign. Null when the campaign had no active delivery run: it was cancelled immediately and none of its remaining recipients are sent." } }, "required": [ "operationId" ] } ] }, "StopCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignStopOperation" } }, "required": [ "success", "data" ] }, "RescheduleCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignOperation" } }, "required": [ "success", "data" ] }, "RescheduleCampaignRequest": { "type": "object", "properties": { "scheduledAt": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true, "maximum": 8640000000000000, "description": "The new start time as a Unix timestamp in milliseconds. `null`, or a time that is not in the future, starts the campaign now." } }, "required": [ "scheduledAt" ], "additionalProperties": false }, "RequeueCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "success", "data" ] }, "RequeueCampaignRequest": { "type": "object", "properties": { "includeSkippedError": { "type": "boolean" } } }, "CampaignRecipient": { "type": "object", "properties": { "id": { "type": "string" }, "phone": { "type": "string" }, "variables": { "type": "object", "additionalProperties": {} }, "variantKey": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "skipped" ] }, "attempts": { "type": "integer" }, "lastError": { "type": "string", "nullable": true, "description": "Why the recipient failed or was skipped. `opted_out` means the phone is on the organization's opt-out list." }, "externalMessageId": { "type": "string", "nullable": true }, "queuedAt": { "type": "number" }, "sentAt": { "type": "number", "nullable": true }, "deliveredAt": { "type": "number", "nullable": true }, "readAt": { "type": "number", "nullable": true }, "failedAt": { "type": "number", "nullable": true }, "respondedAt": { "type": "number", "nullable": true } }, "required": [ "id", "phone", "variables", "variantKey", "status", "attempts", "lastError", "externalMessageId", "queuedAt", "sentAt", "deliveredAt", "readAt", "failedAt", "respondedAt" ] }, "CampaignRecipientPageInfo": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "nextCursor", "hasMore" ] }, "ListCampaignRecipientsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRecipient" } }, "page": { "$ref": "#/components/schemas/CampaignRecipientPageInfo" } }, "required": [ "success", "data", "page" ] }, "InvalidRecipientRow": { "type": "object", "properties": { "row": { "type": "integer", "minimum": 1, "description": "1-based position of the entry in the request (or spreadsheet row number for a file import, where the header is row 1)." }, "reason": { "type": "string", "enum": [ "missing_phone", "invalid_phone", "invalid_variables", "invalid_entry" ] } }, "required": [ "row", "reason" ] }, "AddCampaignRecipientsResult": { "type": "object", "properties": { "campaignId": { "type": "string" }, "added": { "type": "integer", "description": "Recipients added by this request." }, "recipientCount": { "type": "integer", "description": "Recipients on the campaign after this request." }, "duplicateCount": { "type": "integer", "description": "Valid entries skipped because the phone was repeated in the request or is already on the campaign." }, "invalidCount": { "type": "integer" }, "invalidRows": { "type": "array", "items": { "$ref": "#/components/schemas/InvalidRecipientRow" }, "maxItems": 20, "description": "Up to 20 invalid entries." } }, "required": [ "campaignId", "added", "recipientCount", "duplicateCount", "invalidCount", "invalidRows" ] }, "AddCampaignRecipientsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AddCampaignRecipientsResult" } }, "required": [ "success", "data" ] }, "AddCampaignRecipientsRequest": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRecipientInput" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "recipients" ] }, "QuickLink": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "initial", "add_connection", "reauthorization" ] }, "connectionGoal": { "type": "string", "enum": [ "single", "hybrid" ] }, "addConnection": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "id": { "type": "string", "description": "Stable QuickLink identifier, prefixed `ql_`." }, "url": { "type": "string", "description": "Hosted connection URL. Share it only with the person holding the phone." }, "session": { "type": "string", "description": "Session name that receives the connected number." }, "expiresAt": { "type": "string", "nullable": true, "description": "Null for new persistent QuickLinks. Legacy links retain their ISO-8601 expiry." } }, "required": [ "purpose", "connectionGoal", "id", "url", "session", "expiresAt" ] }, "QuickLinkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/QuickLink" } }, "required": [ "success", "data" ] }, "QuickLinkConfiguration": { "type": "object", "properties": { "testing": { "type": "object", "properties": { "country": { "type": "string" }, "configuration": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "maxLength": 139 } }, "additionalProperties": false }, "accountType": { "type": "string", "enum": [ "personal", "business" ] }, "replyBehavior": { "type": "string", "enum": [ "off", "echo" ] }, "failureScenario": { "type": "string", "enum": [ "none", "reject-send" ] }, "historyFixtureId": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "editable": { "type": "array", "items": { "type": "string", "enum": [ "profile.name", "profile.status", "accountType", "replyBehavior", "failureScenario", "historyFixtureId" ] }, "maxItems": 3 } }, "additionalProperties": false }, "prefillPhone": { "type": "string", "pattern": "^\\+?\\d{6,15}$" }, "connectionPreference": { "type": "string", "enum": [ "cloud", "linked", "both" ] }, "connectionEnforcement": { "type": "string", "enum": [ "prefer", "force" ] }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "qr", "pairing" ] }, "minItems": 1, "maxItems": 2, "description": "Linked Devices methods offered for this connection." }, "defaultMethod": { "type": "string", "nullable": true, "enum": [ "qr", "pairing", null ], "description": "Linked Devices method opened first. Omit to inherit the saved project setting, or set null to choose by recipient device." }, "allowPhoneChange": { "type": "boolean" }, "historySync": { "type": "object", "properties": { "consent": { "type": "string", "enum": [ "ask", "force_on", "force_off" ] }, "mode": { "type": "string", "enum": [ "metadata_only", "deliver" ] }, "requestFull": { "type": "boolean" } }, "additionalProperties": false }, "hms": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "enum": [ false ] } }, "required": [ "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "enabled": { "type": "boolean", "enum": [ true ] }, "region": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" }, "policy": { "type": "string", "enum": [ "short", "standard", "extended", "compliance", "enterprise_archive" ] }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 2555 }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "legalHold": { "type": "boolean" } }, "required": [ "enabled", "region", "policy" ], "additionalProperties": false } ] }, "observation": { "type": "object", "properties": { "presenceMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "typingMode": { "type": "string", "enum": [ "off", "events", "cache" ] }, "labelMode": { "type": "string", "enum": [ "off", "events", "cache", "project" ] }, "quickReplyMode": { "type": "string", "enum": [ "off", "events", "cache" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Connection, pairing, phone, and history overrides. Omitted fields inherit saved defaults. Presentation, legal links, and callbacks belong to saved project settings." }, "CreateQuickLinkRequest": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "initial", "add_connection" ], "description": "Initial setup, or add a transport to an existing session without replacing the Number." }, "connectionGoal": { "type": "string", "enum": [ "single", "hybrid" ] }, "session": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Existing session name. Required only for add_connection." }, "addConnection": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "projectId": { "type": "string", "format": "uuid", "description": "Project that receives the connected number. Required for organization keys with more than one project." }, "customerId": { "type": "string", "format": "uuid", "description": "Customer that owns the connected number when Customers is enabled for the project." }, "billingControls": { "type": "object", "properties": { "limitCredits": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1000000 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [ "limitCredits", "priority" ], "additionalProperties": false, "description": "Initial monthly spending limit and funding priority for a real Number. Requires a team key with billing:manage or a live team owner/admin on Pay-As-You-Go. Applied atomically before pairing admission." }, "externalId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\x00-\\x1f\\x7f]+$", "description": "Integrator correlation copied to the resulting session. May repeat across invitations; does not grant access." }, "configuration": { "$ref": "#/components/schemas/QuickLinkConfiguration" } }, "additionalProperties": false }, "HybridQuickLinkAvailabilityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "resumeQuickLinkId": { "type": "string", "nullable": true }, "allowed": { "type": "boolean" }, "addConnection": { "type": "string", "nullable": true, "enum": [ "linked_devices", "official_api", null ] }, "connections": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "status": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "kind", "status", "enabled" ] } } }, "required": [ "resumeQuickLinkId", "allowed", "addConnection", "connections" ] } }, "required": [ "success", "data" ] }, "CloudSyncStatus": { "type": "object", "properties": { "contacts": { "type": "object", "properties": { "request": { "type": "string", "enum": [ "not_applicable", "not_requested", "pending", "requesting", "accepted", "declined", "unknown" ], "description": "Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt." }, "receiptRecorded": { "type": "boolean" } }, "required": [ "request", "receiptRecorded" ] }, "history": { "type": "object", "properties": { "request": { "type": "string", "enum": [ "not_applicable", "not_requested", "pending", "requesting", "accepted", "declined", "unknown" ] }, "receiptRecorded": { "type": "boolean" }, "delivery": { "type": "string", "enum": [ "not_applicable", "not_requested", "unconfirmed", "partial", "complete", "declined" ], "description": "Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists." } }, "required": [ "request", "receiptRecorded", "delivery" ] } }, "required": [ "contacts", "history" ] }, "QuickLinkStatus": { "type": "object", "properties": { "id": { "type": "string" }, "purpose": { "type": "string", "enum": [ "initial", "add_connection", "reauthorization" ] }, "connectionGoal": { "type": "string", "enum": [ "single", "hybrid" ] }, "addConnection": { "type": "string", "enum": [ "linked_devices", "official_api" ] }, "status": { "type": "string", "enum": [ "pending", "opened", "linked", "connected", "failed", "cancelled" ] }, "session": { "type": "string" }, "expiresAt": { "type": "string", "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true, "description": "Connected phone in E.164 once the link is connected." }, "errorCode": { "type": "string", "nullable": true }, "hybridPhase": { "type": "string", "nullable": true, "enum": [ "cloud_setup", "linked_pairing", "repair_linked", "ready", null ] }, "onboarding": { "type": "object", "nullable": true, "properties": { "stage": { "type": "string" }, "connection": { "type": "string", "nullable": true }, "coexistence": { "type": "boolean", "nullable": true }, "contactsSync": { "type": "string" }, "historySync": { "type": "string" }, "historyProgress": { "type": "integer", "minimum": 0, "maximum": 100 }, "errorCode": { "type": "string", "nullable": true }, "sync": { "$ref": "#/components/schemas/CloudSyncStatus" } }, "required": [ "stage", "connection", "coexistence", "contactsSync", "historySync", "historyProgress", "errorCode", "sync" ], "description": "Durable connection and sync progress; omitted when the onboarding service is unavailable, null when no record exists. Sync request and delivery evidence are independent of the connection stage." } }, "required": [ "id", "purpose", "connectionGoal", "status", "session", "expiresAt", "openedAt", "connectedAt", "phone", "errorCode", "hybridPhase" ] }, "QuickLinkStatusResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/QuickLinkStatus" } }, "required": [ "success", "data" ] }, "CloudCredentialHealth": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "healthy", "action_required", "unknown" ], "description": "`healthy`: every check passed. `action_required`: a check failed and the Number needs reauthorization or a change in Meta. `unknown`: Meta could not be reached or returned an incomplete answer; the check is retried. `pending`: not checked since the credentials were saved." }, "checkedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the last validation completed, or null before the first one." }, "nextCheckAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the next scheduled validation becomes due." }, "token": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "valid", "expired", "invalid", "unknown" ] }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Expiry reported by Meta; null for a token without an expiry or when unknown." } }, "required": [ "status", "expiresAt" ] }, "missingPermissions": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp_business_messaging", "whatsapp_business_management" ] }, "description": "Required permissions the saved token lacks for this WhatsApp Business Account." }, "phoneRegistration": { "type": "string", "enum": [ "registered", "not_registered", "unknown" ], "description": "Whether Meta reports the phone number as connected to the Cloud API." }, "webhookSubscription": { "type": "string", "enum": [ "subscribed", "not_subscribed", "unknown" ], "description": "Whether the app that issued the token is subscribed to the WhatsApp Business Account's webhooks." }, "failureCode": { "type": "string", "nullable": true, "enum": [ "app_credentials_rejected", "token_expired", "token_invalid", "token_app_mismatch", "permission_missing", "phone_not_registered", "webhook_not_subscribed", "credentials_unreadable", "meta_unavailable", "meta_response_invalid", null ], "description": "The first failed or inconclusive check, or null when healthy." } }, "required": [ "status", "checkedAt", "nextCheckAt", "token", "missingPermissions", "phoneRegistration", "webhookSubscription", "failureCode" ] }, "CloudCredentialHealthResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CloudCredentialHealth" } }, "required": [ "success", "data" ] }, "CloudReauthorization": { "type": "object", "properties": { "quicklinkId": { "type": "string", "description": "QuickLink identifier, prefixed `ql_`. Read its progress with `GET /messaging/quicklinks/{id}`." }, "url": { "type": "string", "description": "Hosted link. Share it only with the person who manages the Number's Meta assets." }, "session": { "type": "string" } }, "required": [ "quicklinkId", "url", "session" ] }, "CloudReauthorizationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CloudReauthorization" } }, "required": [ "success", "data" ] }, "PublicQuickLinkError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "data": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "whatsappPhone": { "type": "string" }, "registered": { "type": "boolean", "nullable": true, "description": "Whether WhatsApp registration was confirmed. Null means the result is unknown." }, "pushName": { "type": "string", "nullable": true }, "pictureUrl": { "type": "string", "nullable": true }, "accountType": { "type": "string", "enum": [ "whatsapp", "business_app", "cloud_api", "coexistence", "unknown", "unregistered" ] } }, "required": [ "phone", "registered", "pushName", "pictureUrl" ] } } }, "required": [ "candidates" ] } }, "required": [ "error" ] }, "EmbeddedSignupResult": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 4096 }, "wabaId": { "type": "string", "pattern": "^\\d+$" }, "phoneNumberId": { "type": "string", "pattern": "^\\d+$" }, "coexistence": { "type": "boolean", "default": true }, "historySync": { "type": "boolean", "default": false } }, "required": [ "code", "wabaId", "phoneNumberId" ], "additionalProperties": false }, "QuickLinkState": { "type": "object", "properties": { "testing": { "type": "object", "nullable": true, "properties": { "country": { "type": "string" }, "configuration": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "maxLength": 139 } }, "additionalProperties": false }, "accountType": { "type": "string", "enum": [ "personal", "business" ] }, "replyBehavior": { "type": "string", "enum": [ "off", "echo" ] }, "failureScenario": { "type": "string", "enum": [ "none", "reject-send" ] }, "historyFixtureId": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "editable": { "type": "array", "items": { "type": "string", "enum": [ "profile.name", "profile.status", "accountType", "replyBehavior", "failureScenario", "historyFixtureId" ] } }, "state": { "type": "string", "enum": [ "pending", "starting", "ready" ] }, "phone": { "type": "string" } }, "required": [ "country", "configuration", "editable", "state", "phone" ] }, "historyConfiguration": { "type": "object", "nullable": true, "properties": { "mode": { "type": "string", "enum": [ "metadata_only", "deliver" ] }, "requestFull": { "type": "boolean" } }, "required": [ "mode", "requestFull" ] }, "historyConsent": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "declined", null ] }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "opened", "linked", "connected", "failed", "cancelled" ] }, "purpose": { "type": "string", "enum": [ "initial", "add_connection", "reauthorization" ] }, "connectionGoal": { "type": "string", "enum": [ "single", "hybrid" ] }, "addConnection": { "type": "string", "nullable": true, "enum": [ "linked_devices", "official_api", null ] }, "hybridPhase": { "type": "string", "nullable": true, "enum": [ "cloud_setup", "linked_pairing", "repair_linked", "ready", null ] }, "expiresAt": { "type": "string", "nullable": true }, "redirectUrl": { "type": "string", "nullable": true, "format": "uri", "description": "Snapshotted failure callback for a failed link. Omitted for non-failed states." }, "connections": { "type": "array", "items": { "type": "string", "enum": [ "cloud", "linked" ] } }, "selectedConnection": { "type": "string", "nullable": true, "enum": [ "cloud", "linked", null ] }, "connectionPreference": { "type": "string", "enum": [ "cloud", "linked", "both" ] }, "connectionEnforcement": { "type": "string", "enum": [ "prefer", "force" ] }, "cloud": { "type": "object", "nullable": true, "properties": { "appId": { "type": "string" }, "configId": { "type": "string" } }, "required": [ "appId", "configId" ] }, "onboarding": { "type": "object", "nullable": true, "properties": { "stage": { "type": "string" }, "connection": { "type": "string", "nullable": true }, "coexistence": { "type": "boolean", "nullable": true }, "contactsSync": { "type": "string" }, "historySync": { "type": "string" }, "historyProgress": { "type": "integer", "minimum": 0, "maximum": 100 }, "errorCode": { "type": "string", "nullable": true }, "sync": { "$ref": "#/components/schemas/CloudSyncStatus" } }, "required": [ "stage", "connection", "coexistence", "contactsSync", "historySync", "historyProgress", "errorCode", "sync" ] }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "qr", "pairing" ] } }, "defaultMethod": { "type": "string", "nullable": true, "enum": [ "qr", "pairing", null ] }, "businessName": { "type": "string" }, "headline": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "successMessage": { "type": "string", "nullable": true }, "supportUrl": { "type": "string", "nullable": true }, "privacyUrl": { "type": "string", "nullable": true }, "termsUrl": { "type": "string", "nullable": true }, "theme": { "type": "string", "enum": [ "light", "dark", "system" ] }, "accent": { "type": "string", "nullable": true }, "shape": { "type": "string", "nullable": true, "enum": [ "square", "rounded", "pill", null ] }, "radiusPx": { "type": "number", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "hideWatermark": { "type": "boolean" }, "historySync": { "type": "string", "enum": [ "ask", "force_on", "force_off" ] }, "phoneStep": { "type": "object", "properties": { "confirmed": { "type": "boolean" }, "allowChange": { "type": "boolean" }, "noNumber": { "type": "boolean" }, "allowNoNumber": { "type": "boolean" } }, "required": [ "confirmed", "allowChange", "noNumber", "allowNoNumber" ] }, "prefillPhone": { "type": "string", "nullable": true }, "phoneIdentity": { "type": "object", "nullable": true, "properties": { "registered": { "type": "boolean", "nullable": true, "description": "Whether WhatsApp registration was confirmed. Null means the result is unknown." }, "phone": { "type": "string" }, "whatsappPhone": { "type": "string", "nullable": true }, "accountType": { "type": "string", "enum": [ "whatsapp", "business_app", "cloud_api", "coexistence", "unknown", "unregistered" ] }, "pushName": { "type": "string", "nullable": true }, "pictureUrl": { "type": "string", "nullable": true, "format": "uri" } }, "required": [ "registered", "phone", "whatsappPhone", "accountType", "pushName", "pictureUrl" ] }, "customer": { "type": "boolean", "description": "True when the link assigns the number to a Customer." }, "session": { "type": "object", "properties": { "status": { "type": "string" }, "phone": { "type": "string", "nullable": true } }, "required": [ "status", "phone" ] }, "qrSvg": { "type": "string", "nullable": true, "description": "Inline SVG of the current WhatsApp QR code, when the QR method is offered and the number is not linked yet." }, "errorCode": { "type": "string", "nullable": true } }, "required": [ "testing", "historyConfiguration", "historyConsent", "id", "status", "purpose", "connectionGoal", "addConnection", "hybridPhase", "expiresAt", "connections", "selectedConnection", "connectionPreference", "connectionEnforcement", "cloud", "onboarding", "methods", "defaultMethod", "businessName", "headline", "description", "successMessage", "supportUrl", "privacyUrl", "termsUrl", "theme", "accent", "shape", "radiusPx", "logoUrl", "hideWatermark", "historySync", "phoneStep", "prefillPhone", "phoneIdentity", "customer", "session", "qrSvg", "errorCode" ] }, "QuickLinkCodeRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 6, "maxLength": 20 } }, "required": [ "phone" ] }, "QuickLinkConfirmRequest": { "type": "object", "properties": { "historySync": { "type": "boolean" } } }, "EmbeddedSignupRequest": { "type": "object", "properties": { "quicklinkId": { "type": "string", "pattern": "^ql_[a-zA-Z0-9]+$" }, "projectId": { "type": "string", "format": "uuid" }, "result": { "$ref": "#/components/schemas/EmbeddedSignupResult" } }, "required": [ "quicklinkId" ], "additionalProperties": false }, "TestEventFixtureList": { "type": "object", "properties": { "fixtures": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "message.received", "message.ack", "message.failed", "call.received", "call.missed", "call.ended", "session.status", "session.restriction_updated", "template.status" ] }, "description": { "type": "string" }, "overrides": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "description", "overrides" ] } } }, "required": [ "fixtures" ] }, "TriggerTestEventResponse": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "message.received", "message.ack", "message.failed", "call.received", "call.missed", "call.ended", "session.status", "session.restriction_updated", "template.status" ] }, "session": { "type": "string" }, "delivery": { "type": "string", "enum": [ "generated", "simulated" ] }, "eventId": { "type": "string", "nullable": true, "format": "uuid" }, "source": { "type": "string", "enum": [ "test", "runtime" ] } }, "required": [ "event", "session", "delivery", "eventId", "source" ] }, "TestEventOverrides": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "from": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "pushName": { "type": "string", "minLength": 1, "maxLength": 64 }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker" ] }, "caption": { "type": "string", "minLength": 1, "maxLength": 1024 }, "ackStatus": { "type": "string", "enum": [ "delivered", "read", "played", "error" ] }, "messageId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "failureReason": { "type": "string", "enum": [ "invalid_recipient", "session_not_connected", "ack_timeout", "send_failed", "blocked_by_safety" ] }, "video": { "type": "boolean" }, "durationSeconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "callEndReason": { "type": "string", "enum": [ "user_hangup", "timeout", "lost_connection", "rejected", "call_restricted" ] }, "restrictionActive": { "type": "boolean" }, "status": { "type": "string", "enum": [ "CONNECTING", "CONNECTED", "DISCONNECTED" ] }, "statusReason": { "type": "string", "enum": [ "SCAN_QR", "AUTO_RECONNECT", "FAILED", "MANUAL_STOP", "QR_TIMEOUT", "LOGGED_OUT", "TEMPORARY_BAN", "STREAM_ERROR" ] }, "templateName": { "type": "string", "pattern": "^[a-z0-9_]{1,512}$" }, "templateStatus": { "type": "string", "enum": [ "APPROVED", "REJECTED" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false }, "TestingPhoneState": { "type": "object", "properties": { "session": { "type": "string" }, "phone": { "type": "string", "description": "The Test number, in E.164 format." }, "online": { "type": "boolean", "description": "True while the simulated phone is running." }, "devices": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": "integer" } }, "required": [ "deviceId" ] }, "description": "Companions linked to the phone, such as Polymorfa's own session and Inspector." } }, "required": [ "session", "phone", "online", "devices" ] }, "TestingPhoneMessageRequest": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$", "description": "Another Test number in the same project, in E.164 format." }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "to", "text" ], "additionalProperties": false }, "TestingPhoneMessage": { "type": "object", "properties": { "session": { "type": "string" }, "to": { "type": "string" }, "messageId": { "type": "string", "nullable": true } }, "required": [ "session", "to", "messageId" ] }, "TestingPhoneUnlink": { "type": "object", "properties": { "session": { "type": "string" }, "deviceId": { "type": "integer" }, "unlinked": { "type": "boolean", "enum": [ true ] } }, "required": [ "session", "deviceId", "unlinked" ] }, "TestDropinTestingPhoneState": { "type": "object", "properties": { "session": { "type": "string" }, "phone": { "type": "string", "description": "The Test number, in E.164 format." }, "online": { "type": "boolean", "description": "True while the simulated phone is running." }, "devices": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": "integer" } }, "required": [ "deviceId" ] }, "description": "Companions linked to the phone, such as Polymorfa's own session and Inspector." } }, "required": [ "session", "phone", "online", "devices" ] }, "TestDropinPublicError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "billing_error", "conflict_error", "rate_limit_error", "api_error", "upstream_error" ] }, "code": { "type": "string", "enum": [ "zero_knowledge_session", "invalid_parameter", "invalid_credential", "entitlement_required", "cloud_template_authority_restricted", "gate_limit_reached", "billing_credit_required", "addon_required", "safe_mode_not_entitled", "warmup_plan_not_entitled", "method_not_allowed", "permission_denied", "missing_scope", "resource_not_found", "hms_not_enabled", "media_fetch_failed", "resource_gone", "feature_unavailable", "stream_cursor_invalid", "stream_cursor_expired", "stream_connection_limit_reached", "state_conflict", "team_deletion_scheduled", "hybrid_routing_paused", "hybrid_choice_required", "hybrid_transition_ineligible", "hybrid_automation_unavailable", "hybrid_group_linked_devices_unavailable", "hybrid_transport_unavailable", "hybrid_target_reference_unavailable", "send_outcome_unknown", "idempotency_conflict", "idempotency_in_progress", "idempotency_completed", "idempotency_outcome_unknown", "call_claimed", "call_not_ringing", "connection_limit", "unsupported_for_connection", "call_permission_required", "invalid_sip_trunk", "calls_disabled", "call_recipient_opted_out", "call_destination_blocked", "call_permission_request_limited", "call_permission_granted", "order_status_transition_invalid", "order_cancellation_failed", "call_opt_out_limit", "number_restricted", "sip_trunk_in_use", "sip_trunk_revision_conflict", "sip_trunk_limit", "sip_unavailable", "voice_not_enabled", "provider_credential_invalid", "provider_unavailable", "asset_not_ready", "voice_asset_in_use", "voice_asset_revision_conflict", "voice_unavailable", "rate_limit_exceeded", "internal_error", "operation_not_supported", "upstream_failure", "service_unavailable", "credential_verification_unavailable", "session_not_ready", "command_dispatch_failed", "result_unknown", "parent_bsuid_not_supported", "recipient_not_on_whatsapp", "conversation_window_closed", "template_not_approved", "media_too_large", "whatsapp_rate_limited", "new_chat_limit_reached", "marketing_disabled_on_cloud_api", "whatsapp_account_restricted", "whatsapp_authorization_required", "whatsapp_payment_method_required", "whatsapp_number_not_registered", "whatsapp_groups_ineligible", "whatsapp_group_creation_paused", "whatsapp_group_limit_reached", "whatsapp_group_full", "whatsapp_group_suspended", "whatsapp_group_has_no_participants", "bansafe_suspended", "bansafe_org_suspended", "bansafe_cold_blocked", "bansafe_cold_held", "bansafe_throttled", "bansafe_daily_allowance_reached", "bansafe_accounting_unavailable", "bansafe_send_outcome_unknown", "campaigns_not_entitled", "campaign_throughput_capped", "campaign_approval_required", "campaign_approval_stale", "campaign_variables_missing" ] }, "message": { "type": "string" }, "param": { "type": "string", "nullable": true }, "request_id": { "type": "string", "description": "Matches the X-Request-Id response header. Include it when you contact support." }, "request_log_url": { "type": "string", "format": "uri", "description": "Console page that shows this request. Returned only to organization and project credentials whose request was logged." } }, "required": [ "type", "code", "message", "param", "request_id" ] }, "data": { "type": "string", "nullable": true, "enum": [ null ], "description": "Always null for a failed request." }, "docs": { "type": "string", "format": "uri" } }, "required": [ "error", "data", "docs" ] }, "TestDropinTestingPhoneMessageRequest": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$", "description": "Another Test number in the same project, in E.164 format." }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "to", "text" ], "additionalProperties": false }, "TestDropinTestingPhoneMessage": { "type": "object", "properties": { "session": { "type": "string" }, "to": { "type": "string" }, "messageId": { "type": "string", "nullable": true } }, "required": [ "session", "to", "messageId" ] }, "TestDropinTestingPhoneUnlink": { "type": "object", "properties": { "session": { "type": "string" }, "deviceId": { "type": "integer" }, "unlinked": { "type": "boolean", "enum": [ true ] } }, "required": [ "session", "deviceId", "unlinked" ] }, "TestDropinTriggerTestEventRequest": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "message.received", "message.ack", "message.failed", "call.received", "call.missed", "call.ended", "session.status", "session.restriction_updated", "template.status" ], "description": "Fixture name. Each name is the event type it produces." }, "overrides": { "$ref": "#/components/schemas/TestDropinTestEventOverrides" }, "fromNumber": { "type": "string", "minLength": 1, "maxLength": 128, "description": "message.received only. Send a simulated text message from this other connected Test number in the same project instead of generating an event." } }, "required": [ "event" ], "additionalProperties": false }, "TestDropinTestEventOverrides": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "from": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "pushName": { "type": "string", "minLength": 1, "maxLength": 64 }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker" ] }, "caption": { "type": "string", "minLength": 1, "maxLength": 1024 }, "ackStatus": { "type": "string", "enum": [ "delivered", "read", "played", "error" ] }, "messageId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "failureReason": { "type": "string", "enum": [ "invalid_recipient", "session_not_connected", "ack_timeout", "send_failed", "blocked_by_safety" ] }, "video": { "type": "boolean" }, "durationSeconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "callEndReason": { "type": "string", "enum": [ "user_hangup", "timeout", "lost_connection", "rejected", "call_restricted" ] }, "restrictionActive": { "type": "boolean" }, "status": { "type": "string", "enum": [ "CONNECTING", "CONNECTED", "DISCONNECTED" ] }, "statusReason": { "type": "string", "enum": [ "SCAN_QR", "AUTO_RECONNECT", "FAILED", "MANUAL_STOP", "QR_TIMEOUT", "LOGGED_OUT", "TEMPORARY_BAN", "STREAM_ERROR" ] }, "templateName": { "type": "string", "pattern": "^[a-z0-9_]{1,512}$" }, "templateStatus": { "type": "string", "enum": [ "APPROVED", "REJECTED" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false }, "TestDropinTriggerTestEventResponse": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "message.received", "message.ack", "message.failed", "call.received", "call.missed", "call.ended", "session.status", "session.restriction_updated", "template.status" ] }, "session": { "type": "string" }, "delivery": { "type": "string", "enum": [ "generated", "simulated" ] }, "eventId": { "type": "string", "nullable": true, "format": "uuid" }, "source": { "type": "string", "enum": [ "test", "runtime" ] } }, "required": [ "event", "session", "delivery", "eventId", "source" ] }, "TestDropinTestEventFixtureList": { "type": "object", "properties": { "fixtures": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "message.received", "message.ack", "message.failed", "call.received", "call.missed", "call.ended", "session.status", "session.restriction_updated", "template.status" ] }, "description": { "type": "string" }, "overrides": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "description", "overrides" ] } } }, "required": [ "fixtures" ] } }, "headers": { "X-RateLimit-Limit": { "description": "Team request quota per rolling minute, when the per-team request limiter applies.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests left in the per-team quota; zero when this limiter rejects the request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.", "schema": { "type": "integer", "minimum": 0 } }, "TestDropinX-RateLimit-Limit": { "description": "Team request quota per rolling minute, when the per-team request limiter applies.", "schema": { "type": "integer", "minimum": 1 } }, "TestDropinX-RateLimit-Remaining": { "description": "Requests left in the per-team quota; zero when this limiter rejects the request.", "schema": { "type": "integer", "minimum": 0 } }, "TestDropinX-RateLimit-Reset": { "description": "Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.", "schema": { "type": "integer", "minimum": 0 } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Polymorfa organization key (pmfa_ prefix), project token (pmfa_pt_ prefix) where supported, or short-lived client token (pmfa_ct_ prefix). Organization and project keys may be personal or service-account owned and enforce selected action scopes. Organization keys cover the team and its projects; project tokens stay inside one project. Client tokens stay inside their live project and session and enforce their client rules." } } }, "paths": { "/ping": { "get": { "operationId": "ping", "tags": [ "Health" ], "summary": "Liveness probe", "security": [], "responses": { "200": { "description": "Pong", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Full service health check", "security": [], "responses": { "200": { "description": "Required readiness checks pass; optional diagnostics may report degraded or in-progress state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "One or more services unhealthy or draining", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/messaging/info/version": { "get": { "operationId": "getVersion", "tags": [ "Info" ], "summary": "Get API version info", "security": [], "responses": { "200": { "description": "Version info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } } } }, "/messaging/info/status": { "get": { "operationId": "getStatus", "tags": [ "Info" ], "summary": "Get API runtime status", "security": [], "responses": { "200": { "description": "Status info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } } } }, "/messaging/bridge/route": { "get": { "operationId": "getBridgeRoute", "x-required-scope": "bridge:connect", "tags": [ "Bridge" ], "summary": "Verify a project token, resolve live project authority, and return the regional WSS endpoint.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "wsUrl": { "type": "string", "format": "uri" }, "region": { "type": "string", "enum": [ "BR", "US", "IN", "Auto" ] }, "kind": { "type": "string", "enum": [ "sandbox", "production" ] }, "signal": { "type": "string", "enum": [ "customer", "bartender" ] }, "tokenKind": { "type": "string", "enum": [ "project" ] }, "expiresAt": { "type": "integer", "minimum": 0 } }, "required": [ "wsUrl", "region", "kind", "signal", "tokenKind", "expiresAt" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "bridge:connect" }, "description": "**Required scope:** `bridge:connect`" } }, "/messaging/features/evaluate": { "post": { "operationId": "evaluateFeatures", "tags": [ "Features" ], "summary": "Evaluate feature availability", "description": "Returns feature decisions for the authenticated organization or project. Client credentials cannot access this operation. Machine requests do not record experiment exposure.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" }, "keys": { "type": "array", "items": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" }, "maxItems": 50 }, "measurementAllowed": { "type": "boolean", "default": false } }, "required": [ "surface", "keys" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Feature decisions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "decision": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" }, "version": { "type": "integer" }, "available": { "type": "boolean" }, "enrolled": { "type": "boolean" }, "variant": { "type": "string", "nullable": true }, "experimentRevision": { "type": "integer", "nullable": true, "minimum": 1, "description": "Published experiment policy revision for an assigned native experiment; null otherwise." }, "experimentAssigned": { "type": "boolean" } }, "required": [ "key", "version", "available", "enrolled", "variant", "experimentRevision", "experimentAssigned" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "termsRevision": { "type": "string", "nullable": true }, "withdrawal": { "type": "string", "nullable": true }, "exposureToken": {} }, "required": [ "decision", "title", "description", "termsRevision", "withdrawal", "exposureToken" ] } } }, "required": [ "success", "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid feature request", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } } }, "401": { "description": "Authentication required", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } } }, "403": { "description": "Credential cannot access feature evaluation", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } }, "413": { "description": "Request exceeds 16 KiB", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } } } } } }, "/messaging/{session}/pair/qr": { "get": { "operationId": "getQRCode", "tags": [ "Pairing" ], "summary": "Get QR code for device pairing", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sessions:manage`\n\nDirect-pairing access must be enabled for the team that owns this Number. Use [QuickLink](/integrations/quicklink) when direct pairing is unavailable. Requests without access return 403.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "enum": [ "json", "image" ], "default": "json" }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "QR code data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetQRCodeResponse" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Direct-pairing access is required for this Number. Use QuickLink when it is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API sessions:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/pair/code": { "post": { "operationId": "requestPairCode", "tags": [ "Pairing" ], "summary": "Request a pairing code for a phone number", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sessions:manage`\n\nDirect-pairing access must be enabled for the team that owns this Number. Use [QuickLink](/integrations/quicklink) when direct pairing is unavailable. Requests without access return 403.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairCodeRequest" } } } }, "responses": { "200": { "description": "Pairing code issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPairCodeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Direct-pairing access is required for this Number. Use QuickLink when it is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API sessions:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/routing/hybrid": { "get": { "operationId": "getHybridRoutingPolicy", "tags": [ "Messages" ], "summary": "Read a team, project or Number routing policy", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "enum": [ "team", "project", "session" ] }, "required": true, "name": "scope", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "projectId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": false, "name": "session", "in": "query" } ], "responses": { "200": { "description": "Routing policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridRoutingPolicyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:read" }, "description": "**Required scope:** `sessions:read`" }, "put": { "operationId": "setHybridRoutingPolicy", "tags": [ "Messages" ], "summary": "Set a routing policy with a revision guard", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "enum": [ "team", "project", "session" ] }, "required": true, "name": "scope", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "projectId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": false, "name": "session", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetHybridRoutingPolicy" } } } }, "responses": { "200": { "description": "Updated routing policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridRoutingPolicyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" }, "description": "**Required scope:** `sessions:manage`" } }, "/messaging/{session}/hybrid-link": { "get": { "operationId": "getHybridLinkState", "tags": [ "Sessions" ], "summary": "Read the Number's Hybrid connection state", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Hybrid state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridLinkStateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API sessions:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sessions:read`" }, "put": { "operationId": "setHybridLinkPaused", "tags": [ "Sessions" ], "summary": "Pause or resume Hybrid sending", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "string", "format": "uuid" }, "paused": { "type": "boolean" } }, "required": [ "expectedRevision", "paused" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Hybrid pause state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridLinkPauseResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Routing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API sessions:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sessions:manage`" } }, "/messaging/{session}/messages/send": { "post": { "operationId": "sendMessage", "tags": [ "Messages" ], "summary": "Send a message", "description": "**Protocols:** Linked Device API · Meta Cloud API · Polymorfa Hybrid Link\n\n**Required scope:** `messages:write`\n\nSend a message to a conversation. Put exactly one message kind inside content. Testing sessions send only to active testing numbers in the same project; supply the recipient phoneNumber.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "example": { "conversation": { "phoneNumber": "+15550001111" }, "content": { "text": "Hello" } } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Paid service is restricted; review billing and entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or resource access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`unsupported_for_connection`: call permission requests need a Cloud API number; `call_permission_granted`: the person already granted permanent permission. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "The supplied media URL could not be fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "`call_permission_request_limited`: WhatsApp limits how often this person can be asked for call permission.", "headers": { "Retry-After": { "description": "Seconds until the limiting window resets, when WhatsApp reports a reset time.", "schema": { "type": "integer", "minimum": 1 } }, "Polymorfa-RateLimit-Reason": { "description": "The limit that blocked the request.", "schema": { "type": "string", "enum": [ "call_permission_request" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } } }, "500": { "description": "Unexpected service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "501": { "description": "`operation_not_supported`: the number's connection cannot send this content, such as a poll, or a URL, call or copy-code button on an official WhatsApp Business number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Messaging provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Session or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "504": { "description": "Result unknown after timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API Meta Cloud API Polymorfa Hybrid Link messages:write" }, "x-protocols": [ "Linked Device API", "Meta Cloud API", "Polymorfa Hybrid Link" ] } }, "/messaging/{session}/messages/seen": { "post": { "operationId": "sendSeen", "tags": [ "Messages" ], "summary": "Mark messages as seen", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeenRequest" } } } }, "responses": { "200": { "description": "Seen marker confirmed by the messaging backend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageActionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Paid service is restricted; review billing and entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or resource access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing or operation conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Unexpected service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Messaging provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Session or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "504": { "description": "Result unknown after timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API Meta Cloud API Polymorfa Hybrid Link messages:write" }, "x-protocols": [ "Linked Device API", "Meta Cloud API", "Polymorfa Hybrid Link" ], "description": "**Protocols:** Linked Device API · Meta Cloud API · Polymorfa Hybrid Link\n\n**Required scope:** `messages:write`" } }, "/messaging/{session}/messages/typing": { "post": { "operationId": "setTyping", "tags": [ "Messages" ], "summary": "Set typing indicator for a chat", "description": "**Protocols:** Linked Device API · Meta Cloud API\n\n**Required scope:** `messages:write`\n\nOn a Linked Devices number, `state` sets typing, recording or paused. On an official WhatsApp Business number, send `state: \"typing\"` with the `id` of a message you received; this marks that message read and shows a typing indicator until you reply or 25 seconds pass. On a Number with both connections, this method uses the Linked Devices connection; use the Graph API status request for official typing. Other states return `501`, and a missing `id` returns `400`.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypingRequest" } } } }, "responses": { "200": { "description": "Typing state confirmed by the messaging backend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageActionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Paid service is restricted; review billing and entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or resource access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing or operation conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Unexpected service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "501": { "description": "`operation_not_supported`: official WhatsApp Business numbers support only the `typing` state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Messaging provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Session or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "504": { "description": "Result unknown after timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API Meta Cloud API messages:write" }, "x-protocols": [ "Linked Device API", "Meta Cloud API" ] } }, "/messaging/{session}/messages/react": { "post": { "operationId": "sendReaction", "tags": [ "Messages" ], "summary": "React to a message", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactRequest" } } } }, "responses": { "200": { "description": "Reaction sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionResponse" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Paid service is restricted; review billing and entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or resource access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing or operation conflict. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Unexpected service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Messaging provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Session or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "504": { "description": "Result unknown after timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API Meta Cloud API Polymorfa Hybrid Link messages:write" }, "x-protocols": [ "Linked Device API", "Meta Cloud API", "Polymorfa Hybrid Link" ], "description": "**Protocols:** Linked Device API · Meta Cloud API · Polymorfa Hybrid Link\n\n**Required scope:** `messages:write`" } }, "/messaging/{session}/messages/star": { "post": { "operationId": "starMessage", "tags": [ "Messages" ], "summary": "Star or unstar a message", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarRequest" } } } }, "responses": { "200": { "description": "Star status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageActionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Paid service is restricted; review billing and entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or resource access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Routing or operation conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Unexpected service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Messaging provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Session or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "504": { "description": "Result unknown after timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API messages:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `messages:write`" } }, "/messaging/{session}/operations/{operationId}": { "get": { "operationId": "getMessageOperation", "tags": [ "Messages" ], "summary": "Read a Hybrid send operation without repeating it", "security": [ { "BearerAuth": [] } ], "x-required-scope": "operations:read", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "operationId", "in": "path" } ], "responses": { "200": { "description": "Operation metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageOperationResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Operation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Operation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Operation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Operation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Operation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Operation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API operations:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `operations:read`" } }, "/messaging/{session}/chats/{conversation}/messages/{messageId}": { "put": { "operationId": "editMessage", "tags": [ "Chats" ], "summary": "Edit a previously sent message", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "messageId", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageRequest" } } } }, "responses": { "200": { "description": "Message edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_conflict", "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.", "param": null }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:manage`" }, "delete": { "operationId": "deleteMessage", "tags": [ "Chats" ], "summary": "Delete a previously sent message", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "messageId", "in": "path" }, { "schema": { "type": "string", "enum": [ "auto", "linked_devices", "official_api" ] }, "required": false, "name": "transport", "in": "query" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Message deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_conflict", "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.", "param": null }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-Polymorfa-Operation-Id": { "description": "Hybrid operation ID when a send is reserved. Read its status after an uncertain result; do not submit a new key.", "schema": { "type": "string", "format": "uuid" } }, "X-Polymorfa-Transport": { "description": "Transport selected by Hybrid routing, when a route was admitted.", "schema": { "type": "string", "enum": [ "linked_devices", "official_api" ] } }, "X-Polymorfa-Routing-Reason": { "description": "Reason for the selected Hybrid route, when a route was admitted.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:manage`" }, "get": { "operationId": "getChatMessage", "tags": [ "Chats" ], "summary": "Get a stored message", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `messages:read`\n\nReturns one stored message. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "description": "Conversation ID or E.164 phone number." }, "required": true, "name": "conversation", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "required": true, "name": "messageId", "in": "path" } ], "responses": { "200": { "description": "The message", "headers": { "Polymorfa-Data-Region": { "description": "Data region that served the stored history.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChatMessageResponse" } } } }, "400": { "description": "A filter or cursor is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The history service for the Number's data region is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API messages:read" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/chats/{conversation}/archive": { "post": { "operationId": "archiveChat", "tags": [ "Chats" ], "summary": "Archive a chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" } ], "responses": { "200": { "description": "Chat archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:manage`" } }, "/messaging/{session}/chats/{conversation}/unarchive": { "post": { "operationId": "unarchiveChat", "tags": [ "Chats" ], "summary": "Unarchive a chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" } ], "responses": { "200": { "description": "Chat unarchived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:manage`" } }, "/messaging/{session}/chats/{conversation}/disappearing": { "put": { "operationId": "setChatDisappearingTimer", "tags": [ "Chats" ], "summary": "Set the disappearing-message timer for a chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisappearingTimerRequest" } } } }, "responses": { "200": { "description": "Disappearing-message timer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:manage`" } }, "/messaging/{session}/chats": { "get": { "operationId": "listChats", "tags": [ "Chats" ], "summary": "List stored conversations", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:read`\n\nLists conversations with stored messages for a Number with hosted message storage, most recent activity first. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size, from 1 through 100.", "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque cursor from `nextCursor` or `previousCursor`. Reuse it only with the same path and filters." }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "direct", "group", "channel", "broadcast" ], "description": "Return only conversations of this kind." }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Return conversations with activity at or after this time (ISO 8601)." }, "required": false, "name": "activeSince", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Return conversations whose latest activity is before this time (ISO 8601)." }, "required": false, "name": "activeBefore", "in": "query" } ], "responses": { "200": { "description": "One page of conversations", "headers": { "Polymorfa-Data-Region": { "description": "Data region that served the stored history.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatsResponse" } } } }, "400": { "description": "A filter or cursor is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The history service for the Number's data region is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:read" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/chats/{conversation}": { "get": { "operationId": "getChat", "tags": [ "Chats" ], "summary": "Get a stored conversation", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:read`\n\nReturns one conversation with stored messages. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "description": "Conversation ID or E.164 phone number." }, "required": true, "name": "conversation", "in": "path" } ], "responses": { "200": { "description": "The conversation", "headers": { "Polymorfa-Data-Region": { "description": "Data region that served the stored history.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChatResponse" } } } }, "400": { "description": "A filter or cursor is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The history service for the Number's data region is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:read" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/chats/{conversation}/messages": { "get": { "operationId": "listChatMessages", "tags": [ "Chats" ], "summary": "List stored messages in a conversation", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `messages:read`\n\nLists stored messages in one conversation, newest first by default. Page in either direction with `nextCursor` and `previousCursor`. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "description": "Conversation ID or E.164 phone number." }, "required": true, "name": "conversation", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size, from 1 through 100.", "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque cursor from `nextCursor` or `previousCursor`. Reuse it only with the same path and filters." }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc", "description": "`desc` returns newest messages first; `asc` returns oldest first." }, "required": false, "name": "order", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Return messages sent at or after this time (ISO 8601)." }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Return messages sent before this time (ISO 8601)." }, "required": false, "name": "until", "in": "query" }, { "schema": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` returns messages from contacts; `outbound` returns messages sent by the Number." }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z][a-z_]{0,31}(?:,[a-z][a-z_]{0,31}){0,15}$", "description": "Comma-separated message types, for example `text,image`. Up to 16 types.", "example": "text,image" }, "required": false, "name": "types", "in": "query" } ], "responses": { "200": { "description": "One page of messages", "headers": { "Polymorfa-Data-Region": { "description": "Data region that served the stored history.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatMessagesResponse" } } } }, "400": { "description": "A filter or cursor is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The history service for the Number's data region is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API messages:read" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/chats/{conversation}/messages/{messageId}/media": { "get": { "operationId": "getChatMessageMedia", "tags": [ "Chats" ], "summary": "Download stored message media", "description": "**Protocols:** Meta Cloud API\n\n**Required scopes (all):** `messages:read` · `media:read`\n\nReturns the stored copy of an Official API message's media when `mediaRetrieval.state` is `stored`. Requires `messages:read` and `media:read`. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scopes": [ "messages:read", "media:read" ], "x-required-scope-mode": "all", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "description": "Conversation ID or E.164 phone number." }, "required": true, "name": "conversation", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Opaque Polymorfa resource ID. Keep this value as a string.", "example": "739182640518203" }, "required": true, "name": "messageId", "in": "path" } ], "responses": { "200": { "description": "The media bytes, with the stored content type", "headers": { "Polymorfa-Data-Region": { "description": "Data region that served the stored history.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "A filter or cursor is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number, conversation or message is unavailable, no stored copy exists, or hosted message storage is not enabled (`hms_not_enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The history service for the Number's data region is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API messages:read media:read" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/{session}/chats/{conversation}/service-window": { "get": { "operationId": "getCustomerServiceWindow", "tags": [ "Chats" ], "summary": "Get the customer service window", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `chats:read`\n\nReturns whether free-form messages can be sent to a person from a Number's active Official API connection. WhatsApp's customer service window opens for 24 hours when the person messages or calls the Number. Outside it, only approved templates can be sent. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "description": "Conversation ID or E.164 phone number." }, "required": true, "name": "conversation", "in": "path" } ], "responses": { "200": { "description": "The window state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerServiceWindowResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or conversation is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The Number's regional evidence service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API chats:read" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/{session}/meta-pricing": { "get": { "operationId": "getMetaPricingSummary", "tags": [ "Sessions" ], "summary": "Summarize Meta-reported pricing", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `sessions:read`\n\nCounts the messages sent from the Number's active Official API connection generation by the pricing classification WhatsApp reported for each one. Meta bills your WhatsApp Business Account directly. These counts are not a Polymorfa charge and contain no prices. Each message is counted in the period of its first pricing report. Beta: requires team enrollment.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Start of the period, inclusive (ISO 8601). Defaults to 30 days before `until`." }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "End of the period, exclusive (ISO 8601). Defaults to now. The period can be at most 93 days." }, "required": false, "name": "until", "in": "query" } ], "responses": { "200": { "description": "Meta-reported message counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMetaPricingSummaryResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, is a client token, or the team is not enrolled in the beta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The Number's regional evidence service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API sessions:read" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/{session}/call-permissions/{to}": { "get": { "operationId": "getCallPermission", "tags": [ "Calls" ], "summary": "Get a person's call permission", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `sessions:read`\n\nReturns whether the person has allowed this number to call them. On Cloud API numbers WhatsApp is asked on every request and the answer includes its limits on permission requests and calls. Linked-device numbers return `409 unsupported_for_connection`.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "description": "User ID or phone number in E.164 format (URL-encode `+` as `%2B`)." }, "required": true, "name": "to", "in": "path" } ], "responses": { "200": { "description": "The call permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCallPermissionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`unsupported_for_connection`: the number is not a Cloud API number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "unsupported_for_connection", "message": "The session's connection does not support this call operation.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#unsupported-for-connection" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API sessions:read" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/voip/calls/check": { "post": { "operationId": "checkCall", "tags": [ "Calls" ], "summary": "Check whether a call can be placed", "description": "**Required scope:** `sessions:read`\n\nRuns the checks a call placement runs, without calling: the number's calling switch, the team's do-not-call list and blocked country codes, and on Cloud API numbers the person's call permission and WhatsApp's call limits. If WhatsApp's permission status is unavailable and no other refusal is known, returns 503 service_unavailable. Server credentials only.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallCheckRequest" } } } }, "responses": { "200": { "description": "Check result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCallResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "`service_unavailable`: required call-check state is unavailable; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:read" } } }, "/messaging/voip/call-links": { "post": { "operationId": "voipCreateCallLink", "tags": [ "VoIP" ], "summary": "Create a WhatsApp call link", "description": "**Required scope:** `sessions:manage`\n\nRequires a server credential with sessions:manage and a Linked Device Number with calling enabled. Client tokens and Cloud API-only Numbers are refused. This operation does not place or join a call. Idempotency-Key is not supported; do not automatically retry an unknown outcome. Keep call-link tokens and URLs private.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipCreateCallLinkRequest" } } } }, "responses": { "201": { "description": "Link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipCreatedCallLinkEnvelope" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Unsupported connection or another call-link request is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp failed or returned an invalid response; creation outcome can be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Calling settings, Number authority or the connection are unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/call-links/preview": { "post": { "operationId": "voipPreviewCallLink", "tags": [ "VoIP" ], "summary": "Preview a WhatsApp call link", "description": "**Required scope:** `sessions:manage`\n\nRequires a server credential with sessions:manage and a Linked Device Number with calling enabled. Client tokens and Cloud API-only Numbers are refused. This operation does not place or join a call. Idempotency-Key is not supported; do not automatically retry an unknown outcome. Keep call-link tokens and URLs private.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipPreviewCallLinkRequest" } } } }, "responses": { "200": { "description": "Link preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipPreviewedCallLinkEnvelope" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Unsupported connection or another call-link request is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp failed or returned an invalid response; creation outcome can be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Calling settings, Number authority or the connection are unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/offer": { "post": { "operationId": "voipOffer", "x-internal": true, "tags": [ "VoIP" ], "summary": "Attach a WebRTC connection and receive the pod's answer + ICE servers", "description": "**Required scope:** `sessions:manage`\n\nSubmits the SDP offer for one connection. The offer carries one audio transceiver, a data channel negotiated out of band with label `pmfa.calls` and id 0, and one or more video transceivers. Reusing a `connectionId` replaces that connection.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipOfferRequest" } } } }, "responses": { "200": { "description": "SDP answer with STUN/TURN ICE servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipOfferResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`call_claimed` when another participant claimed the call, `connection_limit` when the call has no free connection, or `state_conflict` when the call is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "call_claimed", "message": "Another participant claimed this call.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#call-claimed" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Call setup rate exceeded for this client token, or its concurrency limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/renegotiate": { "post": { "operationId": "voipRenegotiate", "x-internal": true, "tags": [ "VoIP" ], "summary": "Re-offer on an established connection and receive the pod's answer", "description": "**Required scope:** `sessions:manage`\n\nRenegotiates one connection, for example to add video, add receive transceivers after `video_slots_exhausted`, or restart ICE.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipRenegotiateRequest" } } } }, "responses": { "200": { "description": "SDP answer for the re-offer, on the same peer connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipRenegotiateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`call_claimed` when another participant claimed the call, `connection_limit` when the call has no free connection, or `state_conflict` when the call is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "call_claimed", "message": "Another participant claimed this call.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#call-claimed" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls": { "post": { "operationId": "voipPlaceCall", "tags": [ "VoIP" ], "summary": "Place an outbound call from a session", "description": "**Required scope:** `sessions:manage`\n\nOriginates a WhatsApp call to `to`, an ad-hoc group call to `participants` (2 to 31 distinct E.164 phone numbers or public user IDs), or every remote member of `groupId` (a public group ID). Group rosters must contain 2 to 31 remote members; a membership change during placement refuses the call. Provide exactly one destination form. Group calls require a Linked Device number and check every recipient against the team policy and number restrictions before dialing. The call is owned by the placing participant and rings on the callee's device: `call.accepted` follows when they pick up and `call.ended` when either side hangs up. Carry its audio and video with a Polymorfa Calls SDK. `exclusive: true` claims the call for the placing participant. Client tokens place from their bound session; server credentials must name one. Outbound starts share a rate limit per organization and source session across server credentials and client tokens; client-token rules also apply.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipPlaceCallRequest" } } } }, "responses": { "201": { "description": "Call placed and ringing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipPlacedCallResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "`gate_limit_reached` when an enforced usage limit refuses placement; `entitlement_required` when the account lacks a required capability. The outbound monthly gate remains in record mode until placement reservations are available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "gate_limit_reached", "message": "A usage limit for this team or number was reached.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#gate-limit-reached" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "`call_permission_required` when the recipient has not granted this business permission to call them, `number_restricted` when WhatsApp restricts the number to calling people it has already chatted with and the callee is not one of them (`Retry-After` gives the seconds until the restriction ends, when known), or the credential is not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "call_permission_required", "message": "The recipient has not granted this business permission to call them.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#call-permission-required" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`unsupported_for_connection` when the session's connection cannot place this call (Cloud API calls are audio only), or `state_conflict` when the named session cannot place an outbound call yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "unsupported_for_connection", "message": "The session's connection does not support this call operation.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#unsupported-for-connection" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Outbound call rate exceeded for this organization and source session, or a client-token setup or concurrency limit was reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "501": { "description": "Outbound calls are not available on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "operation_not_supported", "message": "This operation is not supported.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#operation-not-supported" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "`upstream_failure` when the Cloud API refused or failed the call action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, call authority cannot be verified, or usage limits could not be checked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/accept": { "post": { "operationId": "voipAcceptCall", "tags": [ "VoIP" ], "summary": "Answer or join a call", "description": "**Required scope:** `sessions:manage`\n\nThe first accept answers a ringing call. `exclusive: true` claims it: other participants then receive `409 call_claimed` for accept and media, and their open connections close. Without a claim, later accepts join the answered call. Retrying with the same participant returns the same result. An exclusive request from another participant on a shared call is refused with `409 call_claimed`.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipAcceptCallRequest" } } } }, "responses": { "200": { "description": "Call answered or joined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipAcceptCallResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`call_claimed` when another participant claimed the call, or `state_conflict` when the call is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "call_claimed", "message": "Another participant claimed this call.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#call-claimed" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/reject": { "post": { "operationId": "voipRejectCall", "tags": [ "VoIP" ], "summary": "Decline a ringing call", "description": "**Required scope:** `sessions:manage`\n\nDeclines a ringing call and releases it. Returns `409 call_not_ringing` when the call is not ringing.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipRejectCallRequest" } } } }, "responses": { "202": { "description": "Call declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`call_not_ringing` when the call was already answered, declined, or ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "call_not_ringing", "message": "The call is no longer ringing.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#call-not-ringing" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/leave": { "post": { "operationId": "voipLeaveCall", "tags": [ "VoIP" ], "summary": "Close one connection without ending the call", "description": "**Required scope:** `sessions:manage`\n\nDisconnects the named connection. The call and the participant's other connections continue. Use `DELETE /voip/calls/{id}` to end the call for everyone.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipLeaveRequest" } } } }, "responses": { "202": { "description": "Connection closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Call not ready — no media session on the owning pod yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/reaction": { "post": { "operationId": "sendCallReaction", "tags": [ "VoIP" ], "summary": "Send or clear a call reaction", "description": "**Required scope:** `sessions:manage`\n\nRequires an attached connection owned by the acting participant, sessions:manage, and voip_signal for client tokens. Linked-device calls only; unsupported backends return 409 unsupported_for_connection. Reactions are transient and are not replayed. Hand state is shared by the Number and restored on media reconnection. Do not automatically retry an uncertain result.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipReactionRequest" } } } }, "responses": { "202": { "description": "Reaction accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The call is not ready (`state_conflict`), or the calling backend does not support this action (`unsupported_for_connection`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/hand": { "post": { "operationId": "setCallHandRaised", "tags": [ "VoIP" ], "summary": "Raise or lower the Number's hand in a call", "description": "**Required scope:** `sessions:manage`\n\nRequires an attached connection owned by the acting participant, sessions:manage, and voip_signal for client tokens. Linked-device calls only; unsupported backends return 409 unsupported_for_connection. Reactions are transient and are not replayed. Hand state is shared by the Number and restored on media reconnection. Do not automatically retry an uncertain result.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipHandRequest" } } } }, "responses": { "202": { "description": "Hand state accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The call is not ready (`state_conflict`), or the calling backend does not support this action (`unsupported_for_connection`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/participants/ring": { "post": { "operationId": "voipRingParticipant", "tags": [ "VoIP" ], "summary": "Ring an existing call participant again", "description": "**Required scope:** `sessions:manage`\n\nRings one non-connected participant already in the upstream call roster. Does not add a participant or change the roster optimistically. Requires the same destination permission as an invitation. Cloud API calls do not support this operation.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipAddParticipantRequest" } } } }, "responses": { "202": { "description": "Ring request accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The call is not ready (`state_conflict`), or the calling backend does not support this action (`unsupported_for_connection`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Call setup rate exceeded for this client token, or its concurrency limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/participants": { "post": { "operationId": "voipAddParticipant", "tags": [ "VoIP" ], "summary": "Invite another party into a live call", "description": "**Required scope:** `sessions:manage`\n\nRings `to` (an E.164 phone number or a user ID) into the call, turning a 1:1 call into a group call. The invitee enters the roster as `invited`; roster changes reach media sockets as `participant_joined` / `participant_state` / `participant_left` frames. 409 until the call has a live leg.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipAddParticipantRequest" } } } }, "responses": { "201": { "description": "Participant invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipAddParticipantResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "`number_restricted` when WhatsApp restricts the number to calling people it has already chatted with and the invitee is not one of them (`Retry-After` gives the seconds until the restriction ends, when known), or the credential is not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "number_restricted", "message": "WhatsApp restricts this number to calling people it has already chatted with. The restriction lifts on its own; follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#number-restricted" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`unsupported_for_connection` when the session connects through the Cloud API, which has no group calls, or `state_conflict` when the call has no live leg yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "unsupported_for_connection", "message": "The session's connection does not support this call operation.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#unsupported-for-connection" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Call setup rate exceeded for this client token, or its concurrency limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}/candidate": { "post": { "operationId": "voipCandidate", "x-internal": true, "tags": [ "VoIP" ], "summary": "Trickle a local ICE candidate to one connection", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipCandidateRequest" } } } }, "responses": { "202": { "description": "Candidate accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Call not ready — no media session on the owning pod yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" }, "description": "**Required scope:** `sessions:manage`" } }, "/messaging/voip/calls/{id}/candidates": { "get": { "operationId": "voipCandidates", "x-internal": true, "tags": [ "VoIP" ], "summary": "Poll remote ICE candidates queued for the browser", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Queued remote candidates (drained on read)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipCandidatesEnvelope" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Call not ready — no media session on the owning pod yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" }, "description": "**Required scope:** `sessions:manage`" } }, "/messaging/voip/calls/{id}/reports": { "post": { "operationId": "voipReportCallDiagnostics", "tags": [ "VoIP" ], "summary": "Report call diagnostics from your app", "description": "**Required scope:** `sessions:manage`\n\nRecords quality figures or an error that your app measured for one of its connections. The Console shows the latest quality report and the reported errors of each connection on the call. Reports are optional and are accepted while the call is live and for 10 minutes after it ends. Each connection can send one quality report every 5 seconds and 20 error reports per minute. At most 200 reports are kept per call: at that limit a quality report replaces the same connection's oldest quality report. A quality report from a connection with no stored quality report, and every error report, is accepted but not stored.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoipCallReportRequest" } } } }, "responses": { "202": { "description": "Report accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict` when the call is not live, ended more than 10 minutes ago, or is outside the credential's boundary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "The connection exceeded its report limit: one quality report every 5 seconds or 20 error reports per minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call authority or report storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/voip/calls/{id}": { "delete": { "operationId": "voipTeardown", "tags": [ "VoIP" ], "summary": "End a call for everyone", "description": "**Required scope:** `sessions:manage`\n\nEnds the call and closes every connection. Repeating the request succeeds.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "call-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Call ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Call not ready — no media session on the owning pod yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Call ended — the pod that owned its media is gone (pod_lost)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/{session}/calls/{callId}/reject": { "post": { "operationId": "rejectCall", "tags": [ "Calls" ], "summary": "Reject an incoming WhatsApp call", "security": [ { "BearerAuth": [] } ], "x-required-scope": "chats:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "callId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectCallRequest" } } } }, "responses": { "200": { "description": "Call rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API chats:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `chats:manage`" } }, "/messaging/{session}/groups": { "get": { "operationId": "listGroups", "tags": [ "Groups" ], "summary": "List groups the session is a member of", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Group list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGroupsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`" }, "post": { "operationId": "createGroup", "tags": [ "Groups" ], "summary": "Create a new group", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupRequest" } } } }, "responses": { "200": { "description": "Group created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/join-info": { "get": { "operationId": "getGroupJoinInfo", "tags": [ "Groups" ], "summary": "Look up group info for an invite code", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "code", "in": "query" } ], "responses": { "200": { "description": "Join info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupJoinInfoResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`" } }, "/messaging/{session}/groups/join": { "post": { "operationId": "joinGroup", "tags": [ "Groups" ], "summary": "Join a group by invite code", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinGroupRequest" } } } }, "responses": { "200": { "description": "Joined group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}": { "get": { "operationId": "getGroup", "tags": [ "Groups" ], "summary": "Get group details", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Group details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`" }, "delete": { "operationId": "deleteGroup", "tags": [ "Groups" ], "summary": "Leave a group (DELETE alias)", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Left group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/leave": { "post": { "operationId": "leaveGroup", "tags": [ "Groups" ], "summary": "Leave a group", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Left group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/subject": { "put": { "operationId": "setGroupSubject", "tags": [ "Groups" ], "summary": "Set group subject (name)", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetGroupFieldRequest" } } } }, "responses": { "200": { "description": "Subject updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/description": { "put": { "operationId": "setGroupDescription", "tags": [ "Groups" ], "summary": "Set group description", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetGroupFieldRequest" } } } }, "responses": { "200": { "description": "Description updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/invite-code": { "get": { "operationId": "getGroupInviteCode", "tags": [ "Groups" ], "summary": "Get the current group invite code", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Invite code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupInviteCodeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`" } }, "/messaging/{session}/groups/{id}/invite-code/revoke": { "post": { "operationId": "revokeGroupInviteCode", "tags": [ "Groups" ], "summary": "Revoke the current invite code and generate a new one", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "New invite code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGroupInviteCodeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/participants": { "get": { "operationId": "getGroupParticipants", "tags": [ "Groups" ], "summary": "List group participants", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Participant list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupParticipantsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`" } }, "/messaging/{session}/groups/{id}/participants/add": { "post": { "operationId": "addGroupParticipants", "tags": [ "Groups" ], "summary": "Add participants to a group", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupParticipantsRequest" } } } }, "responses": { "200": { "description": "Participants added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/participants/remove": { "post": { "operationId": "removeGroupParticipants", "tags": [ "Groups" ], "summary": "Remove participants from a group", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupParticipantsRequest" } } } }, "responses": { "200": { "description": "Participants removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/admin/promote": { "post": { "operationId": "promoteGroupAdmin", "tags": [ "Groups" ], "summary": "Promote participants to admin", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupParticipantsRequest" } } } }, "responses": { "200": { "description": "Participants promoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/admin/demote": { "post": { "operationId": "demoteGroupAdmin", "tags": [ "Groups" ], "summary": "Demote admin participants", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupParticipantsRequest" } } } }, "responses": { "200": { "description": "Participants demoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/picture": { "put": { "operationId": "setGroupPicture", "tags": [ "Groups" ], "summary": "Set the group profile picture", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetGroupPictureRequest" } } } }, "responses": { "200": { "description": "Picture updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/settings/info-edit": { "put": { "operationId": "setGroupInfoEditing", "tags": [ "Groups" ], "summary": "Choose who can edit group information", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupAdminOnlySettingRequest" } } } }, "responses": { "200": { "description": "Group information permission updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/settings/messages": { "put": { "operationId": "setGroupMessaging", "tags": [ "Groups" ], "summary": "Choose who can send group messages", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupAdminOnlySettingRequest" } } } }, "responses": { "200": { "description": "Group messaging permission updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/settings/member-add": { "put": { "operationId": "setGroupMemberAddMode", "tags": [ "Groups" ], "summary": "Choose who can add group members", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberAddModeRequest" } } } }, "responses": { "200": { "description": "Group member-add mode updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/groups/{id}/settings/join-approval": { "put": { "operationId": "setGroupJoinApproval", "tags": [ "Groups" ], "summary": "Require admin approval for invite-link joins", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupJoinApprovalRequest" } } } }, "responses": { "200": { "description": "Group join approval updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`" } }, "/messaging/{session}/official-groups": { "get": { "operationId": "listOfficialGroups", "tags": [ "Official groups" ], "summary": "List Official groups", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`\n\nLists the active groups this Number created through the Official API, newest first as WhatsApp returns them. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_=+/-]{1,512}$", "description": "Cursor from a previous page's `cursors.before`." }, "required": false, "name": "before", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_=+/-]{1,512}$", "description": "Cursor from a previous page's `cursors.after`." }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Groups per page, 1 to 1024. WhatsApp's default is 25." }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfficialGroupsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ] }, "post": { "operationId": "createOfficialGroup", "tags": [ "Official groups" ], "summary": "Create an Official group", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nAsks WhatsApp to create a group. WhatsApp creates it asynchronously and sends a `group.update` event with the group's conversation ID and invite link. A Number can create at most 10,000 groups, and each group holds at most 8 participants besides your business. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOfficialGroupRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOfficialGroupResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}": { "get": { "operationId": "getOfficialGroup", "tags": [ "Official groups" ], "summary": "Get an Official group", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`\n\nReturns the group's subject, description, participants, suspension and join approval setting. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOfficialGroupResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ] }, "patch": { "operationId": "updateOfficialGroup", "tags": [ "Official groups" ], "summary": "Update an Official group", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nChanges the group's subject or description. A `group.update` event with action `settings_updated` reports which changes WhatsApp applied. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOfficialGroupRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOfficialGroupResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] }, "delete": { "operationId": "deleteOfficialGroup", "tags": [ "Official groups" ], "summary": "Delete an Official group", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nDeletes the group and removes every participant, including your business. Nobody can message the group afterwards. A `group.update` event with action `deleted` confirms it. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOfficialGroupResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/invite-link": { "get": { "operationId": "getOfficialGroupInviteLink", "tags": [ "Official groups" ], "summary": "Get an Official group invite link", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`\n\nReturns the link people open to join the group. Participants can only join with the link. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOfficialGroupInviteLinkResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/invite-link/reset": { "post": { "operationId": "resetOfficialGroupInviteLink", "tags": [ "Official groups" ], "summary": "Reset an Official group invite link", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nCreates a new invite link. Every earlier link stops working. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetOfficialGroupInviteLinkResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/participants/remove": { "post": { "operationId": "removeOfficialGroupParticipants", "tags": [ "Official groups" ], "summary": "Remove Official group participants", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nRemoves up to eight participants. A removed participant cannot rejoin with the invite link. A `group.participant` event reports each removal. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveOfficialGroupParticipantsRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveOfficialGroupParticipantsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/join-requests": { "get": { "operationId": "listOfficialGroupJoinRequests", "tags": [ "Official groups" ], "summary": "List Official group join requests", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:read`\n\nLists open requests to join a group that requires join approval. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_=+/-]{1,512}$", "description": "Cursor from a previous page's `cursors.before`." }, "required": false, "name": "before", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_=+/-]{1,512}$", "description": "Cursor from a previous page's `cursors.after`." }, "required": false, "name": "after", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfficialGroupJoinRequestsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:read" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/join-requests/approve": { "post": { "operationId": "approveOfficialGroupJoinRequests", "tags": [ "Official groups" ], "summary": "Approve Official group join requests", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nApproves open join requests. Approved people can join with the invite link. Requests WhatsApp could not approve are listed in `failed`. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialGroupJoinRequestIds" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveOfficialGroupJoinRequestsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/join-requests/reject": { "post": { "operationId": "rejectOfficialGroupJoinRequests", "tags": [ "Official groups" ], "summary": "Reject Official group join requests", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nRejects open join requests. The person can request to join again. Requests WhatsApp could not reject are listed in `failed`. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialGroupJoinRequestIds" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectOfficialGroupJoinRequestsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/official-groups/{group}/pins": { "post": { "operationId": "pinOfficialGroupMessage", "tags": [ "Official groups" ], "summary": "Pin or unpin an Official group message", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `groups:manage`\n\nPins a message for 1 to 30 days, or unpins it. At most three messages stay pinned; a new pin unpins the oldest. Beta: requires team enrollment and a Number with an Official API connection whose WhatsApp Business Account is an Official Business Account.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "groups:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Conversation ID of the group.", "example": "739182640518203" }, "required": true, "name": "group", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinOfficialGroupMessageRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinOfficialGroupMessageResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "The credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing restrictions prevent the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "The credential lacks the scope, the team is not enrolled in the beta (`feature_unavailable`), the number is not eligible for groups (`whatsapp_groups_ineligible`), group creation is paused (`whatsapp_group_creation_paused`), or the group is suspended (`whatsapp_group_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "The Number or group is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Number has no Official API connection (`unsupported_for_connection`), or a WhatsApp group limit was reached (`whatsapp_group_limit_reached`, `whatsapp_group_full`).. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "WhatsApp is limiting group requests from this number (`whatsapp_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "WhatsApp's response could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "A required service is unavailable. For a change, WhatsApp may have applied it: read the group before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API groups:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/{session}/contacts": { "get": { "operationId": "listContacts", "tags": [ "Contacts" ], "summary": "List all contacts known to the session", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Contact list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/check": { "get": { "operationId": "checkContacts", "tags": [ "Contacts" ], "summary": "Check if phone numbers are registered on WhatsApp", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "required": true, "name": "phone", "in": "query", "style": "form", "explode": false } ], "responses": { "200": { "description": "Contact check results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckContactsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/blocked": { "get": { "operationId": "getBlocklist", "tags": [ "Contacts" ], "summary": "Get blocked contacts", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Blocked contacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBlocklistResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/{contactId}": { "get": { "operationId": "getContact", "tags": [ "Contacts" ], "summary": "Get a contact by stable user ID", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/{contactId}/picture": { "get": { "operationId": "getContactPicture", "tags": [ "Contacts" ], "summary": "Get a contact's profile picture URL", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Profile picture URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactPictureResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/{contactId}/info": { "get": { "operationId": "getUserInfo", "tags": [ "Contacts" ], "summary": "Get live WhatsApp user metadata", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "User metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserInfoResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/{contactId}/devices": { "get": { "operationId": "getUserDevices", "tags": [ "Contacts" ], "summary": "Get a contact's linked devices", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Linked devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserDevicesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/{contactId}/business-profile": { "get": { "operationId": "getBusinessProfile", "tags": [ "Contacts" ], "summary": "Get a WhatsApp business profile", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Business profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessProfileResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/contacts/{contactId}/block": { "post": { "operationId": "blockContact", "tags": [ "Contacts" ], "summary": "Block a contact", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Contact blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:manage`" } }, "/messaging/{session}/contacts/{contactId}/unblock": { "post": { "operationId": "unblockContact", "tags": [ "Contacts" ], "summary": "Unblock a contact", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Contact unblocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:manage`" } }, "/messaging/{session}/business/linked-accounts": { "get": { "operationId": "getBusinessLinkedAccounts", "tags": [ "Business App" ], "summary": "Read live accounts linked to the connected WhatsApp Business App", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Live linked-account state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessLinkedAccountsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" } }, "/messaging/{session}/business/eligibility": { "get": { "operationId": "getBusinessEligibility", "tags": [ "Business App" ], "summary": "Read live feature eligibility for the connected WhatsApp Business App", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Live business feature eligibility", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessEligibilityResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" } }, "/messaging/{session}/business/profile": { "get": { "operationId": "getOwnBusinessProfile", "tags": [ "Business App" ], "summary": "Read the connected WhatsApp Business App profile", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Live business profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOwnBusinessProfileResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:read`" }, "patch": { "operationId": "updateBusinessProfile", "tags": [ "Business App" ], "summary": "Update the connected WhatsApp Business App profile", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBusinessProfileResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/profile/cover-photo": { "put": { "operationId": "setBusinessCoverPhoto", "tags": [ "Business App" ], "summary": "Set the connected WhatsApp Business App cover photo", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCoverPhotoRequest" } } } }, "responses": { "200": { "description": "Cover photo set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBusinessCoverPhotoResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/profile/cover-photo/{coverPhotoId}": { "delete": { "operationId": "deleteBusinessCoverPhoto", "tags": [ "Business App" ], "summary": "Delete the connected WhatsApp Business App cover photo", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": true, "name": "coverPhotoId", "in": "path" } ], "responses": { "200": { "description": "Cover photo removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBusinessCoverPhotoResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/compliance": { "get": { "operationId": "getBusinessMerchantCompliance", "tags": [ "Business App" ], "summary": "Read merchant compliance details for the connected WhatsApp Business App account", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Live merchant compliance details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessMerchantComplianceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:read`" }, "put": { "operationId": "setBusinessMerchantCompliance", "tags": [ "Business App" ], "summary": "Replace merchant compliance details for the connected WhatsApp Business App account", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessMerchantCompliance" } } } }, "responses": { "200": { "description": "Merchant compliance details updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBusinessMerchantComplianceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/quick-replies": { "post": { "operationId": "createBusinessQuickReply", "tags": [ "Business App" ], "summary": "Create a WhatsApp Business App quick reply", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessQuickReplyMutation" } } } }, "responses": { "200": { "description": "Quick reply created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessQuickReplyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" }, "get": { "operationId": "listBusinessQuickReplies", "tags": [ "Business App" ], "summary": "List remembered WhatsApp Business App quick replies", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Best-effort quick reply list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBusinessQuickRepliesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:read`" } }, "/messaging/{session}/business/quick-replies/{quickReplyId}": { "put": { "operationId": "setBusinessQuickReply", "tags": [ "Business App" ], "summary": "Replace a WhatsApp Business App quick reply", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[0-9]+$" }, "required": true, "name": "quickReplyId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessQuickReplyMutation" } } } }, "responses": { "200": { "description": "Quick reply replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBusinessQuickReplyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" }, "delete": { "operationId": "deleteBusinessQuickReply", "tags": [ "Business App" ], "summary": "Delete a WhatsApp Business App quick reply", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[0-9]+$" }, "required": true, "name": "quickReplyId", "in": "path" } ], "responses": { "200": { "description": "Quick reply deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBusinessQuickReplyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/catalog": { "get": { "operationId": "getBusinessCatalog", "tags": [ "Business App" ], "summary": "Read a WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256, "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048 }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024 }, "required": false, "name": "width", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024 }, "required": false, "name": "height", "in": "query" } ], "responses": { "200": { "description": "Live catalog page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessCatalogResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Upstream WhatsApp request failed or its response could not be mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" }, "post": { "operationId": "createBusinessCatalog", "tags": [ "Business App" ], "summary": "Create a catalog for the connected WhatsApp Business App account", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Catalog created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessCatalogResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/catalog/cart": { "patch": { "operationId": "setBusinessCartEnabled", "tags": [ "Business App" ], "summary": "Enable or disable the connected WhatsApp Business App catalog cart", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCartSettingRequest" } } } }, "responses": { "200": { "description": "Cart setting updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBusinessCartEnabledResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/products/{productId}": { "get": { "operationId": "getBusinessProduct", "tags": [ "Business App" ], "summary": "Read a WhatsApp Business App product", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "productId", "in": "path" }, { "schema": { "type": "string", "maxLength": 256, "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "query" } ], "responses": { "200": { "description": "Live product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessProductResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Upstream WhatsApp request failed or its response could not be mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" }, "put": { "operationId": "updateBusinessProduct", "tags": [ "Business App" ], "summary": "Replace a product in the connected WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "productId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProductMutationRequest" } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBusinessProductResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" }, "delete": { "operationId": "deleteBusinessProduct", "tags": [ "Business App" ], "summary": "Delete a product from the connected WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "productId", "in": "path" } ], "responses": { "200": { "description": "Product deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBusinessProductResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/products": { "post": { "operationId": "createBusinessProduct", "tags": [ "Business App" ], "summary": "Create a product in the connected WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProductMutationRequest" } } } }, "responses": { "200": { "description": "Product created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessProductResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/products/{productId}/visibility": { "patch": { "operationId": "setBusinessProductVisibility", "tags": [ "Business App" ], "summary": "Hide or show a product in the connected WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "productId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProductVisibilityRequest" } } } }, "responses": { "200": { "description": "Product visibility updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBusinessProductVisibilityResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/products/{productId}/appeal": { "post": { "operationId": "appealBusinessProduct", "tags": [ "Business App" ], "summary": "Request a review of a rejected WhatsApp Business App catalog product", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "productId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCatalogAppealRequest" } } } }, "responses": { "200": { "description": "Product appeal submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppealBusinessProductResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/collections": { "get": { "operationId": "getBusinessCollections", "tags": [ "Business App" ], "summary": "Read WhatsApp Business App collections", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256, "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048 }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "required": false, "name": "collectionLimit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "itemLimit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024 }, "required": false, "name": "width", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024 }, "required": false, "name": "height", "in": "query" } ], "responses": { "200": { "description": "Live collection page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessCollectionsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Upstream WhatsApp request failed or its response could not be mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" }, "post": { "operationId": "createBusinessCollection", "tags": [ "Business App" ], "summary": "Create a collection in the connected WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCollectionCreateRequest" } } } }, "responses": { "200": { "description": "Collection created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessCollectionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/collections/{collectionId}": { "get": { "operationId": "getBusinessCollection", "tags": [ "Business App" ], "summary": "Read a WhatsApp Business App collection", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "collectionId", "in": "path" }, { "schema": { "type": "string", "maxLength": 256, "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048 }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024 }, "required": false, "name": "width", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1024 }, "required": false, "name": "height", "in": "query" } ], "responses": { "200": { "description": "Live collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessCollectionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Upstream WhatsApp request failed or its response could not be mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" }, "patch": { "operationId": "updateBusinessCollection", "tags": [ "Business App" ], "summary": "Update a collection and its product membership", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "collectionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCollectionUpdateRequest" } } } }, "responses": { "200": { "description": "Collection updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBusinessCollectionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" }, "delete": { "operationId": "deleteBusinessCollection", "tags": [ "Business App" ], "summary": "Delete a collection from the connected WhatsApp Business App catalog", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "collectionId", "in": "path" } ], "responses": { "200": { "description": "Collection deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBusinessCollectionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/collections/reorder": { "post": { "operationId": "reorderBusinessCollections", "tags": [ "Business App" ], "summary": "Reorder connected WhatsApp Business App catalog collections", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCollectionReorderRequest" } } } }, "responses": { "200": { "description": "Collections reordered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderBusinessCollectionsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/collections/{collectionId}/appeal": { "post": { "operationId": "appealBusinessCollection", "tags": [ "Business App" ], "summary": "Request a review of a rejected WhatsApp Business App catalog collection", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "collectionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCatalogAppealRequest" } } } }, "responses": { "200": { "description": "Collection appeal submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppealBusinessCollectionResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/business/orders/{orderId}/lookup": { "post": { "operationId": "getBusinessOrder", "tags": [ "Business App" ], "summary": "Read WhatsApp Business App order details", "security": [ { "BearerAuth": [] } ], "x-required-scope": "business:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "orderId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessOrderLookupRequest" } } } }, "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusinessOrderResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Upstream WhatsApp request failed or its response could not be mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API business:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `business:read`" } }, "/messaging/{session}/identities/resolve": { "get": { "operationId": "resolveIdentity", "tags": [ "Identities" ], "summary": "Resolve a user alias to a stable user ID", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "phoneNumber", "in": "query" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": false, "name": "id", "in": "query" }, { "schema": { "type": "string", "minLength": 3, "maxLength": 35 }, "required": false, "name": "username", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}$" }, "required": false, "name": "usernameKey", "in": "query" } ], "responses": { "200": { "description": "Stable user ID and known aliases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIdentityResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/users/{id}/security-code": { "get": { "operationId": "getUserSecurityCode", "tags": [ "Users" ], "summary": "Get an identity verification code for a user", "security": [ { "BearerAuth": [] } ], "x-required-scope": "contacts:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Identity verification code and display QR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSecurityCodeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API contacts:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `contacts:read`" } }, "/messaging/{session}/channels": { "get": { "operationId": "listChannels", "tags": [ "Channels" ], "summary": "List channels the session follows", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Channel list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChannelsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:read`" }, "post": { "operationId": "createChannel", "tags": [ "Channels" ], "summary": "Create a new channel", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelRequest" } } } }, "responses": { "200": { "description": "Channel created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}": { "get": { "operationId": "getChannel", "tags": [ "Channels" ], "summary": "Get channel details", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:read`" }, "delete": { "operationId": "deleteChannel", "tags": [ "Channels" ], "summary": "Delete a channel", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteChannelResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Upstream WhatsApp request failed or its response could not be mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}/messages": { "get": { "operationId": "listChannelMessages", "tags": [ "Channels" ], "summary": "List channel messages", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "count", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "required": false, "name": "before", "in": "query" } ], "responses": { "200": { "description": "Channel messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChannelMessagesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:read`" } }, "/messaging/{session}/channels/{id}/message-updates": { "get": { "operationId": "listChannelMessageUpdates", "tags": [ "Channels" ], "summary": "List channel view and reaction updates", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "count", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0 }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "required": false, "name": "after", "in": "query" } ], "responses": { "200": { "description": "Channel message updates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChannelMessageUpdatesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:read`" } }, "/messaging/{session}/channels/{id}/messages/{messageId}/viewed": { "post": { "operationId": "markChannelMessageViewed", "tags": [ "Channels" ], "summary": "Mark a channel message as viewed", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "messageId", "in": "path" } ], "responses": { "200": { "description": "Message marked viewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}/messages/{messageId}/reaction": { "post": { "operationId": "reactToChannelMessage", "tags": [ "Channels" ], "summary": "React to a channel message", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "messageId", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelReactionRequest" } } } }, "responses": { "200": { "description": "Reaction updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_conflict", "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.", "param": null }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}/live-updates": { "post": { "operationId": "subscribeChannelLiveUpdates", "tags": [ "Channels" ], "summary": "Subscribe temporarily to channel live updates", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Live-update subscription duration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelLiveUpdatesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:read`" } }, "/messaging/{session}/channels/{id}/follow": { "post": { "operationId": "followChannel", "tags": [ "Channels" ], "summary": "Follow a channel", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel followed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}/unfollow": { "post": { "operationId": "unfollowChannel", "tags": [ "Channels" ], "summary": "Unfollow a channel", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel unfollowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}/mute": { "post": { "operationId": "muteChannel", "tags": [ "Channels" ], "summary": "Mute a channel", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel muted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/channels/{id}/unmute": { "post": { "operationId": "unmuteChannel", "tags": [ "Channels" ], "summary": "Unmute a channel", "security": [ { "BearerAuth": [] } ], "x-required-scope": "channels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel unmuted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API channels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `channels:manage`" } }, "/messaging/{session}/presence": { "post": { "operationId": "setPresence", "tags": [ "Presence" ], "summary": "Set the session's own presence (available / unavailable)", "security": [ { "BearerAuth": [] } ], "x-required-scope": "presence:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPresenceRequest" } } } }, "responses": { "200": { "description": "Presence updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API presence:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `presence:write`" }, "get": { "operationId": "getPresence", "tags": [ "Presence" ], "summary": "Get the session's own presence", "security": [ { "BearerAuth": [] } ], "x-required-scope": "presence:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Presence info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPresenceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API presence:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `presence:read`" } }, "/messaging/{session}/presence/{conversation}": { "get": { "operationId": "getChatPresence", "tags": [ "Presence" ], "summary": "Get presence for a specific chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "presence:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" } ], "responses": { "200": { "description": "Chat presence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChatPresenceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API presence:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `presence:read`" } }, "/messaging/{session}/presence/{conversation}/subscribe": { "post": { "operationId": "subscribePresence", "tags": [ "Presence" ], "summary": "Subscribe to presence updates for a chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "presence:observe", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" } ], "responses": { "200": { "description": "Subscribed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribePresenceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Observation limit exceeded, or the session is inside the suspension window that follows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API presence:observe" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `presence:observe`" } }, "/messaging/projects/{projectId}/safe-mode": { "get": { "operationId": "getProjectSafeMode", "tags": [ "Safe Mode" ], "summary": "Get a project's Safe Mode ceiling", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "Project Safe Mode ceiling, and whether the plan includes BanSafe Lite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProjectSafeModeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:read" }, "description": "**Required scope:** `sessions:read`" }, "put": { "operationId": "updateProjectSafeMode", "tags": [ "Safe Mode" ], "summary": "Set a project's Safe Mode ceiling", "description": "**Required scope:** `sessions:manage`\n\nSets the most visible behaviour any number in this project may use. Presence and read receipts are visible to the people this number messages: turning them on makes the number appear online, exposes last-seen subject to the account's privacy settings, and puts blue ticks on incoming messages. Every axis is off by default and only this request changes it.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "dark", "online_while_sending", "online_hours" ] }, "typing": { "type": "string", "enum": [ "off", "before_text", "before_all" ] }, "reads": { "type": "string", "enum": [ "off", "replied_chats", "all_inbound" ] }, "pacing": { "type": "string", "enum": [ "off", "jittered", "conversation" ] }, "onlineStart": { "type": "integer", "minimum": 0, "maximum": 23 }, "onlineEnd": { "type": "integer", "minimum": 0, "maximum": 23 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Project Safe Mode ceiling updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectSafeModeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Safe Mode is part of BanSafe Lite, which is not included on this number's plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "entitlement_required", "message": "The account needs the required entitlement for this action.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#entitlement-required" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Stored, but a connected number did not confirm the policy; retry the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/{session}/safe-mode": { "get": { "operationId": "getSessionSafeMode", "tags": [ "Safe Mode" ], "summary": "Get a number's effective Safe Mode", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Project ceiling, number override, the effective policy, and whether the plan includes BanSafe Lite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionSafeModeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API sessions:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sessions:read`" }, "put": { "operationId": "updateSessionSafeMode", "tags": [ "Safe Mode" ], "summary": "Set a number's Safe Mode override", "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sessions:manage`\n\nSets one number's Safe Mode. Each axis accepts `inherit` to follow the project ceiling. An override may only be equally or more conservative than the ceiling; a more visible value is refused with `safe_mode_exceeds_project_ceiling`.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "presence": { "type": "string", "enum": [ "inherit", "dark", "online_while_sending", "online_hours" ] }, "typing": { "type": "string", "enum": [ "inherit", "off", "before_text", "before_all" ] }, "reads": { "type": "string", "enum": [ "inherit", "off", "replied_chats", "all_inbound" ] }, "pacing": { "type": "string", "enum": [ "inherit", "off", "jittered", "conversation" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Number Safe Mode override updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionSafeModeResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Safe Mode is part of BanSafe Lite, which is not included on this number's plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "entitlement_required", "message": "The account needs the required entitlement for this action.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#entitlement-required" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Stored, but a connected number did not confirm the policy; retry the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API sessions:manage" }, "x-protocols": [ "Linked Device API" ] } }, "/messaging/projects/{projectId}/warmup-plan": { "get": { "operationId": "getProjectWarmupPlan", "tags": [ "Warm-up plan" ], "summary": "Get a project's warm-up plan", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "Project warm-up plan, its projected curve, and whether the plan includes BanSafe Lite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProjectWarmupPlanResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:read" }, "description": "**Required scope:** `sessions:read`" }, "put": { "operationId": "updateProjectWarmupPlan", "tags": [ "Warm-up plan" ], "summary": "Set a project's warm-up plan", "description": "**Required scope:** `sessions:manage`\n\nTurns the warm-up plan on or off for a project and sets how long the ramp takes and how many messages a number may send on its first day. While the plan is on, a send past a number's allowance is refused with `bansafe_daily_allowance_reached` and campaign recipients are deferred to the next reset.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "warmupDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "dailyStart": { "type": "integer", "minimum": 1, "maximum": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Project warm-up plan updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectWarmupPlanResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "The warm-up plan is part of BanSafe Lite, which is not included on this project's plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "entitlement_required", "message": "The account needs the required entitlement for this action.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#entitlement-required" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Stored, but a connected number did not confirm the plan; retry the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/projects/{projectId}/health-policy": { "get": { "operationId": "getProjectHealthPolicy", "tags": [ "BanSafe" ], "summary": "Get a project's health policy", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "Project health threshold and configured actions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProjectHealthPolicyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:read" }, "description": "**Required scope:** `sessions:read`" }, "put": { "operationId": "updateProjectHealthPolicy", "tags": [ "BanSafe" ], "summary": "Set a project's health policy", "description": "**Required scope:** `sessions:manage`\n\nReplaces the project policy when version matches the stored version. The rule triggers only when an available health estimate is below threshold. Stopping disconnects a session while retaining its linked credentials; logging out requires relinking.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectHealthPolicyInput" } } } }, "responses": { "200": { "description": "Project health policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectHealthPolicyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Version conflict or selected notification integration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/projects/{projectId}/insurance-evidence": { "get": { "operationId": "getProjectInsuranceEvidence", "tags": [ "Ban insurance" ], "summary": "Get ban insurance evidence setting", "description": "**Required scope:** `sessions:read`\n\nBan insurance evidence lets Polymorfa measure what the other devices linked to a number do with it: how many messages they send, to how many people, how fast, and in which hours. Only counts are kept, never messages, contacts, or device names. With it off, a claim can still be filed, but Polymorfa cannot say whether another device caused the ban and a person decides the claim.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "The project's ban insurance evidence setting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProjectInsuranceEvidenceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:read" } }, "put": { "operationId": "updateProjectInsuranceEvidence", "tags": [ "Ban insurance" ], "summary": "Set ban insurance evidence setting", "description": "**Required scope:** `sessions:manage`\n\nBan insurance evidence lets Polymorfa measure what the other devices linked to a number do with it: how many messages they send, to how many people, how fast, and in which hours. Only counts are kept, never messages, contacts, or device names. With it off, a claim can still be filed, but Polymorfa cannot say whether another device caused the ban and a person decides the claim.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:manage", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The project's ban insurance evidence setting was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectInsuranceEvidenceResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Stored, but a connected number did not confirm the change; retry the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "sessions:manage" } } }, "/messaging/projects/{projectId}/observation-policy": { "get": { "operationId": "getProjectObservationPolicy", "tags": [ "Presence", "Labels", "Business App" ], "security": [ { "BearerAuth": [] } ], "x-required-scope": "presence:read", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "Project observation ceiling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProjectObservationPolicyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "presence:read" }, "description": "**Required scope:** `presence:read`" } }, "/messaging/{session}/observation-policy": { "get": { "operationId": "getSessionObservationPolicy", "tags": [ "Presence", "Labels", "Business App" ], "security": [ { "BearerAuth": [] } ], "x-required-scope": "presence:read", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Effective session observation policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionObservationPolicyResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API presence:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `presence:read`" } }, "/messaging/{session}/profile": { "get": { "operationId": "getProfile", "tags": [ "Profile" ], "summary": "Get the session's own profile", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Profile info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProfileResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:read`" } }, "/messaging/{session}/profile/name": { "put": { "operationId": "setProfileName", "tags": [ "Profile" ], "summary": "Set profile display name (push name)", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfileNameRequest" } } } }, "responses": { "200": { "description": "Name updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/profile/status": { "put": { "operationId": "setProfileStatus", "tags": [ "Profile" ], "summary": "Set profile status (about) text", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfileStatusRequest" } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/profile/picture": { "put": { "operationId": "setProfilePicture", "tags": [ "Profile" ], "summary": "Set profile picture", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfilePictureRequest" } } } }, "responses": { "200": { "description": "Picture updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" }, "delete": { "operationId": "deleteProfilePicture", "tags": [ "Profile" ], "summary": "Remove the profile picture", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Picture deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/privacy": { "get": { "operationId": "getPrivacySettings", "tags": [ "Privacy" ], "summary": "Get privacy settings", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Privacy settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacySettingsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:read`" } }, "/messaging/{session}/privacy/disappearing/default": { "put": { "operationId": "setDefaultDisappearingTimer", "tags": [ "Privacy" ], "summary": "Set the default disappearing-message timer", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefaultDisappearingTimerRequest" } } } }, "responses": { "200": { "description": "Default disappearing-message timer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/privacy/{setting}": { "put": { "operationId": "setPrivacySetting", "tags": [ "Privacy" ], "summary": "Update a privacy setting", "security": [ { "BearerAuth": [] } ], "x-required-scope": "profile:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "enum": [ "groupadd", "last", "status", "profile", "readreceipts", "online", "calladd", "messages", "defense", "stickers" ] }, "required": true, "name": "setting", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPrivacySettingRequest" } } } }, "responses": { "200": { "description": "Updated privacy settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedPrivacySettingsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API profile:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `profile:write`" } }, "/messaging/{session}/labels": { "get": { "operationId": "listLabels", "tags": [ "Labels" ], "summary": "List labels defined for the session", "security": [ { "BearerAuth": [] } ], "x-required-scope": "labels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeObservation", "in": "query" } ], "responses": { "200": { "description": "Label list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLabelsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API labels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `labels:read`" }, "post": { "operationId": "createLabel", "tags": [ "Labels" ], "summary": "Create a label", "security": [ { "BearerAuth": [] } ], "x-required-scope": "labels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } } } }, "responses": { "200": { "description": "Label created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API labels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `labels:manage`" } }, "/messaging/{session}/labels/{labelId}": { "put": { "operationId": "updateLabel", "tags": [ "Labels" ], "summary": "Update a label", "security": [ { "BearerAuth": [] } ], "x-required-scope": "labels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "labelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLabelRequest" } } } }, "responses": { "200": { "description": "Label updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The session has no authoritative view of its labels yet. Retry once a cached or project-retained snapshot is complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API labels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `labels:manage`" }, "delete": { "operationId": "deleteLabel", "tags": [ "Labels" ], "summary": "Delete a label", "security": [ { "BearerAuth": [] } ], "x-required-scope": "labels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "labelId", "in": "path" } ], "responses": { "200": { "description": "Label deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API labels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `labels:manage`" } }, "/messaging/{session}/labels/chats/{conversation}": { "get": { "operationId": "getChatLabels", "tags": [ "Labels" ], "summary": "Get labels attached to a chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "labels:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeObservation", "in": "query" } ], "responses": { "200": { "description": "Chat labels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChatLabelsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API labels:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `labels:read`" }, "put": { "operationId": "setChatLabels", "tags": [ "Labels" ], "summary": "Replace the set of labels attached to a chat", "security": [ { "BearerAuth": [] } ], "x-required-scope": "labels:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "conversation", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetChatLabelsRequest" } } } }, "responses": { "200": { "description": "Chat labels updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The session has no authoritative view of its labels yet. Retry once a cached or project-retained snapshot is complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API labels:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `labels:manage`" } }, "/messaging/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhooks for the tenant", "security": [ { "BearerAuth": [] } ], "x-required-scope": "webhooks:manage", "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "webhooks:manage" }, "description": "**Required scope:** `webhooks:manage`" }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Register a new webhook", "security": [ { "BearerAuth": [] } ], "x-required-scope": "webhooks:manage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "webhooks:manage" }, "description": "**Required scope:** `webhooks:manage`" } }, "/messaging/webhooks/{id}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "Get a webhook by id", "security": [ { "BearerAuth": [] } ], "x-required-scope": "webhooks:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebhookResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "webhooks:manage" }, "description": "**Required scope:** `webhooks:manage`" }, "put": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook", "security": [ { "BearerAuth": [] } ], "x-required-scope": "webhooks:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "webhooks:manage" }, "description": "**Required scope:** `webhooks:manage`" }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook", "security": [ { "BearerAuth": [] } ], "x-required-scope": "webhooks:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "webhooks:manage" }, "description": "**Required scope:** `webhooks:manage`" } }, "/messaging/media/{id}": { "get": { "operationId": "downloadMedia", "tags": [ "Media" ], "summary": "Download media (binary stream or redirect to S3)", "security": [ { "BearerAuth": [] } ], "x-required-scope": "media:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Media binary stream", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "302": { "description": "Redirect to S3", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API media:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `media:read`" } }, "/messaging/media/{id}/info": { "get": { "operationId": "getMediaInfo", "tags": [ "Media" ], "summary": "Get media metadata", "security": [ { "BearerAuth": [] } ], "x-required-scope": "media:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Media info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMediaInfoResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API media:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `media:read`" } }, "/messaging/media/{id}/download-and-save": { "post": { "operationId": "downloadAndSaveMedia", "tags": [ "Media" ], "summary": "Download media and persist it to the tenant's S3 bucket", "security": [ { "BearerAuth": [] } ], "x-required-scope": "media:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Persistence queued or already persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Linked Device API media:manage" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `media:manage`" } }, "/messaging/{session}/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "List templates for a Number", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `messages:write`\n\nFor a real Official API Number, including a Hybrid Number, reads the complete template catalog of its WhatsApp Business Account from Meta, stores it, and returns it. A test-mode Cloud Number uses its simulated catalog. A Number with only a Linked Devices connection receives 400. If a catalog read is incomplete, the request fails with 502 and the stored templates are unchanged.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Template list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Meta did not return a complete template catalog; the stored templates are unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The Number's WhatsApp Business Account is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API messages:write" }, "x-protocols": [ "Meta Cloud API" ] }, "post": { "operationId": "createTemplate", "tags": [ "Templates" ], "summary": "Create a template for a Number", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `messages:write`\n\nSubmits the template to Meta for a real Official API Number, including a Hybrid Number, or to the simulator for a test-mode Cloud Number, then stores the receipt. If the provider accepts the template but the receipt cannot be stored, the API imports it from one catalog read; if that also fails, it returns 500 with `template was submitted but could not be stored`. Do not resubmit in that case: list templates to load it. A retry with the same `Idempotency-Key` returns `409 idempotency_completed`. The returned status is the one in the response, or `PENDING` when none is returned. For real Official API Numbers, later approval, rejection and quality changes arrive as `template.status` webhook events and appear in the next list. A Number with only a Linked Devices connection receives 400.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } } }, "responses": { "201": { "description": "Template submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_conflict", "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.", "param": null }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Meta did not complete the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The Number's WhatsApp Business Account is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "default": { "description": "Meta returned a 400-599 error status; the mutation may have an unknown outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API messages:write" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/{session}/templates/{name}": { "get": { "operationId": "getTemplate", "tags": [ "Templates" ], "summary": "Get a template by name", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `messages:write`\n\nRefreshes the Number's provider or simulated template catalog and returns the template with this name and language. `language` defaults to `en_US`. Fails with 502 if the catalog read is incomplete. Real Official API Numbers, including Hybrid Numbers, and test-mode Cloud Numbers are supported. A Number with only a Linked Devices connection receives 400.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "language", "in": "query" } ], "responses": { "200": { "description": "Template detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Meta did not return a complete template catalog; the stored templates are unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The Number's WhatsApp Business Account is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API messages:write" }, "x-protocols": [ "Meta Cloud API" ] }, "patch": { "operationId": "editTemplate", "tags": [ "Templates" ], "summary": "Submit a change to a Meta template", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `messages:write`\n\nChanges the components of one template language in the Number's owned WhatsApp Business Account. A 202 response means Meta accepted the edit request; read the template status to establish whether it is available to send. If the outcome is unknown, read the template again before deciding whether to retry. The Number needs an active Official API connection, including when it also has a Linked Devices connection. A test-mode Cloud Number or a Number with only a Linked Devices connection receives 400.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "language", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditTemplateRequest" } } } }, "responses": { "202": { "description": "Meta accepted the edit request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditTemplateAcceptedResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Account or billing authority refused the edit before Meta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "entitlement_required", "message": "The account needs the required entitlement for this action.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#entitlement-required" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The template changed before the edit was sent to Meta; read it and try again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Meta did not return a complete template catalog; the stored templates are unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The edit was not sent to Meta, or its outcome is unknown; the message says which. Read the template from Meta before retrying an unknown outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "default": { "description": "Meta rejected the edit with a 4xx status; an unknown outcome uses 503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API messages:write" }, "x-protocols": [ "Meta Cloud API" ] }, "delete": { "operationId": "deleteTemplate", "tags": [ "Templates" ], "summary": "Delete a template", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `messages:write`\n\nDeletes every language of the named template from Meta for a real Official API Number, including a Hybrid Number, or from the simulated catalog for a test-mode Cloud Number, then removes the stored copies. A confirmed provider deletion succeeds even if local cleanup fails; the next complete catalog read reconciles the mirror. If the provider rejects the deletion or its result is unknown, the stored templates are kept. A Number with only a Linked Devices connection receives 400.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "messages:write", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "name", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_conflict", "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.", "param": null }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "502": { "description": "Meta did not complete the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "default": { "description": "Meta returned a 400-599 error status; the mutation may have an unknown outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API messages:write" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/projects/{projectSlug}/templates": { "get": { "operationId": "listProjectTemplates", "tags": [ "Templates" ], "summary": "List project message templates", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectTemplatesResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:read" }, "description": "**Required scope:** `templates:read`" }, "post": { "operationId": "createProjectTemplate", "tags": [ "Templates" ], "summary": "Create a project message template", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageTemplateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:manage" }, "description": "**Required scope:** `templates:manage`" } }, "/messaging/projects/{projectSlug}/templates/{id}": { "get": { "operationId": "getProjectTemplate", "tags": [ "Templates" ], "summary": "Get a project message template", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProjectTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:read" }, "description": "**Required scope:** `templates:read`" }, "patch": { "operationId": "updateProjectTemplate", "tags": [ "Templates" ], "summary": "Update a project message template", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMessageTemplateRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:manage" }, "description": "**Required scope:** `templates:manage`" }, "delete": { "operationId": "deleteProjectTemplate", "tags": [ "Templates" ], "summary": "Delete a project message template", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:manage" }, "description": "**Required scope:** `templates:manage`" } }, "/messaging/projects/{projectSlug}/templates/{id}/preview": { "post": { "operationId": "previewProjectTemplate", "tags": [ "Templates" ], "summary": "Render a template preview (idealized) or surface-specific output", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewMessageTemplateRequest" } } } }, "responses": { "200": { "description": "Rendered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewProjectTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:read" }, "description": "**Required scope:** `templates:read`" } }, "/messaging/projects/{projectSlug}/templates/{id}/submit": { "post": { "operationId": "submitProjectTemplateToMeta", "tags": [ "Templates" ], "summary": "Submit a project template for approval", "description": "**Required scope:** `templates:manage`\n\nAccepts any number, so one integration handles both connection types; check `submission` in the response. A Cloud API number needs Meta approval: the template is rendered into a Meta create-template payload, submitted through that number, recorded as a per-number approval pointer (cloudLinks), and returned with `submission.status` PENDING. Read the Number's template catalog for Meta's review result. Any other number needs no review: nothing is sent to Meta and the template is returned with `submission.status` APPROVED and `submission.autoApproved` true. Incomplete or invalid definitions return 400 for every number; passing local validation does not guarantee Meta approval.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "templates:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitMessageTemplateRequest" } } } }, "responses": { "200": { "description": "Submitted to Meta (Cloud API number) or approved automatically (any other number)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitProjectTemplateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "templates:manage" } } }, "/messaging/projects/{projectSlug}/campaigns": { "get": { "operationId": "listCampaigns", "tags": [ "Campaigns" ], "summary": "List campaigns", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCampaignsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:read" }, "description": "**Required scope:** `campaigns:read`" }, "post": { "operationId": "createCampaign", "tags": [ "Campaigns" ], "summary": "Create a campaign", "description": "**Required scope:** `campaigns:manage`\n\nCreates a draft campaign on any plan. `senderConfig.sessionIds` may name numbers that are not yet on a plan that includes Campaigns; launch checks the selection. It is refused with `403 bansafe_org_suspended` while the team is suspended and `400` when `senderConfig.sessionIds` is malformed or a per-number cap is above its safety ceiling.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_conflict", "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.", "param": null }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}": { "get": { "operationId": "getCampaign", "tags": [ "Campaigns" ], "summary": "Get a campaign", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:read" }, "description": "**Required scope:** `campaigns:read`" }, "patch": { "operationId": "updateProjectCampaign", "tags": [ "Campaigns" ], "summary": "Update a campaign", "description": "**Required scope:** `campaigns:manage`\n\nUpdates the fields you send and leaves the rest unchanged. On an unlaunched draft, a new `senderConfig` passes the same checks as create, on any plan; launch checks the selection against live plans. Once the campaign has launched, including a scheduled launch that has not started, a new `senderConfig` must pass the launch checks and can answer `402 campaigns_not_entitled` or `400 invalid_parameter`. `recipientListId` and a different `scheduledAt` are accepted only while the campaign is an unlaunched draft; afterwards they answer `409`. A sender change to a draft that launches while the change is being saved also answers `409`. `sendWindow` changes only while draft or paused; a paused edit answers `409` while sends are in progress. A non-null `scheduledAt` must be integer Unix milliseconds within the JavaScript Date range.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "`campaigns_not_entitled`: a new sender selection on a launched campaign names a number whose plan does not include Campaigns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "campaigns_not_entitled", "message": "This number’s plan does not include Campaigns.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#campaigns-not-entitled" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict`: the campaign has launched and the audience or start time can no longer change, it launched while its sending numbers were being changed, or its send window cannot change in the current state or while sends are in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "`service_unavailable`: number eligibility for a launched campaign's new sender selection could not be checked. Nothing was changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}/analytics": { "get": { "operationId": "getCampaignAnalytics", "tags": [ "Campaigns" ], "summary": "Campaign analytics (funnel, response timing, retries)", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAnalyticsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:read" }, "description": "**Required scope:** `campaigns:read`" } }, "/messaging/projects/{projectSlug}/campaigns/{id}/launch": { "post": { "operationId": "launchCampaign", "tags": [ "Campaigns" ], "summary": "Launch a campaign", "description": "**Required scope:** `campaigns:manage`\n\nStarts a draft campaign. It begins sending at `scheduledAt`, or right away when no start time is set. Launch checks the saved sender selection against live plans: `402 campaigns_not_entitled` when a selected number is missing or its plan does not include Campaigns, or when an unselected campaign's project has no such number; `400 invalid_parameter` on `senderConfig.sessionIds` when a selected number is not connected or the selection mixes sending types; `400 campaign_throughput_capped` when a requested throughput is above its ceiling. The response returns the campaign as it was when the launch was accepted.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchCampaignRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "`campaigns_not_entitled`: a selected number is missing or its plan does not include Campaigns, or the project has no number on such a plan. Drafts are saved on every plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "campaigns_not_entitled", "message": "This number’s plan does not include Campaigns.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#campaigns-not-entitled" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict`: The campaign is not a draft, it is already launched and waiting for its start time, or its sending numbers changed during the launch. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "`service_unavailable`: the selected numbers' plans could not be checked; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "A required service is unavailable. Check completion before repeating a write.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#service-unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}/pause": { "post": { "operationId": "pauseCampaign", "tags": [ "Campaigns" ], "summary": "Pause a campaign", "description": "**Required scope:** `campaigns:manage`\n\nPauses a running campaign. Sends already in progress can still finish.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict`: The campaign is not running, or it has no active delivery run to pause. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}/resume": { "post": { "operationId": "resumeCampaign", "tags": [ "Campaigns" ], "summary": "Resume a campaign", "description": "**Required scope:** `campaigns:manage`\n\nResumes a paused campaign. Its remaining recipients are sent after the same checks as before the pause.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict`: The campaign is not paused, or it has no active delivery run to resume. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}/stop": { "post": { "operationId": "stopCampaign", "tags": [ "Campaigns" ], "summary": "Stop a campaign", "description": "**Required scope:** `campaigns:manage`\n\nCancels a draft, running, or paused campaign. Recipients not yet sent are not sent. The campaign moves to `cancelling` and then to `cancelled` once sends already in progress finish; a campaign with no active delivery run is `cancelled` immediately.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict`: The campaign is already finished or cancelled. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}/reschedule": { "post": { "operationId": "rescheduleCampaign", "tags": [ "Campaigns" ], "summary": "Reschedule a campaign", "description": "**Required scope:** `campaigns:manage`\n\nMoves the start of a launched campaign that is still waiting for it. Set `scheduledAt` to a later or earlier time, or to `null` to start now. The response returns the campaign with its new `scheduledAt`. Sending the current start time again changes nothing. A campaign that has started, finished, is being stopped, or was never launched is refused with `409`; launch a draft with `scheduledAt` instead.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again: it returns `409 idempotency_completed` when the original succeeded, or the original server error, with `Idempotent-Replayed: true`. Reusing the key for a different request returns `409 idempotency_conflict`; a retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleCampaignRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "`state_conflict`: The campaign has already started, is finished or being stopped, or was never launched. The Idempotency-Key already succeeded (`idempotency_completed`), was used for a different request (`idempotency_conflict`), belongs to a request that is still running (`idempotency_in_progress`, with Retry-After), or belongs to a request whose outcome was not recorded (`idempotency_outcome_unknown`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying `idempotency_in_progress`.", "schema": { "type": "integer", "minimum": 0 } }, "Idempotent-Replayed": { "description": "`true` when this response reports the recorded outcome of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/projects/{projectSlug}/campaigns/{id}/requeue": { "post": { "operationId": "requeueCampaign", "tags": [ "Campaigns" ], "summary": "Re-queue failed recipients", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequeueCampaignRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequeueCampaignResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" }, "description": "**Required scope:** `campaigns:manage`" } }, "/messaging/projects/{projectSlug}/campaigns/{id}/recipients": { "get": { "operationId": "listProjectCampaignRecipients", "tags": [ "Campaigns" ], "summary": "List campaign recipients", "description": "**Required scope:** `campaigns:read`\n\nLists a campaign's recipients in queue order with cursor pagination. Filter by `status` to find, for example, recipients skipped because they opted out.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:read", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "skipped" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size, default 25." }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCampaignRecipientsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:read" } }, "post": { "operationId": "addProjectCampaignRecipients", "tags": [ "Campaigns" ], "summary": "Add recipients to a draft campaign", "description": "**Required scope:** `campaigns:manage`\n\nAdds up to 1,000 recipients to a campaign that has not started sending. A phone already on the campaign is skipped. Invalid entries are reported and not added.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "campaigns:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectSlug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCampaignRecipientsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCampaignRecipientsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "The campaign has started sending and no longer accepts recipients", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "conflict_error", "code": "state_conflict", "message": "The request conflicts with the resource state.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#state-conflict" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "campaigns:manage" } } }, "/messaging/quicklinks": { "post": { "operationId": "createQuickLink", "tags": [ "QuickLink" ], "summary": "Create a QuickLink", "description": "**Required scope:** `quicklink:manage`\n\nCreates a persistent hosted link that connects one WhatsApp number to a new session in the project.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "quicklink:manage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuickLinkRequest" } } } }, "responses": { "201": { "description": "QuickLink created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickLinkResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "quicklink:manage" } } }, "/messaging/quicklinks/availability": { "get": { "operationId": "getHybridQuickLinkAvailability", "tags": [ "QuickLink" ], "summary": "Read connection addition availability", "security": [ { "BearerAuth": [] } ], "x-required-scope": "quicklink:manage", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "session", "in": "query" } ], "responses": { "200": { "description": "Connection state and permitted addition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridQuickLinkAvailabilityResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "quicklink:manage" }, "description": "**Required scope:** `quicklink:manage`" } }, "/messaging/quicklinks/{id}": { "get": { "operationId": "getQuickLink", "tags": [ "QuickLink" ], "summary": "Read QuickLink status", "security": [ { "BearerAuth": [] } ], "x-required-scope": "quicklink:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Current QuickLink status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickLinkStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "quicklink:manage" }, "description": "**Required scope:** `quicklink:manage`" }, "delete": { "operationId": "cancelQuickLink", "tags": [ "QuickLink" ], "summary": "Cancel a QuickLink", "description": "**Required scope:** `quicklink:manage`\n\nCancels pending onboarding. Initial Number cleanup is accepted asynchronously and completes only after runtime teardown. Supplementary and reauthorization links cancel only their pending attempts; the existing Number remains. Accepted provider work must finish before cancellation.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "quicklink:manage", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "QuickLink invalidated; Number cleanup pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "quicklink:manage" } } }, "/messaging/{session}/cloud-credentials": { "get": { "operationId": "getCloudCredentialHealth", "tags": [ "Sessions" ], "summary": "Read Meta Cloud API credential health", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `sessions:read`\n\nReturns the latest recurring validation of the Number's Meta Cloud API credentials: token validity, required permissions, phone registration and webhook subscription.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "sessions:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "Credential health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudCredentialHealthResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API sessions:read" }, "x-protocols": [ "Meta Cloud API" ] } }, "/messaging/{session}/cloud-credentials/reauthorize": { "post": { "operationId": "reauthorizeCloudCredentials", "tags": [ "Sessions" ], "summary": "Start guided Meta Cloud API reauthorization", "description": "**Protocols:** Meta Cloud API\n\n**Required scope:** `quicklink:manage`\n\nRequires a project token with `quicklink:manage`. Creates a QuickLink with purpose `reauthorization` that renews the Number's Meta authorization through Embedded Signup. The link is bound to the same Number and phone number and always uses the Meta Cloud API. The Number must be stopped or disconnected; this request never stops it. Cancelling the link before Meta work starts keeps the Number.", "security": [ { "BearerAuth": [] } ], "x-required-scope": "quicklink:manage", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "session", "in": "path" } ], "responses": { "201": { "description": "Reauthorization link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudReauthorizationResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "402": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "501": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "Meta Cloud API quicklink:manage" }, "x-protocols": [ "Meta Cloud API" ] } }, "/quicklink/{token}/phone": { "post": { "operationId": "confirmQuickLinkPhone", "tags": [ "QuickLink" ], "security": [], "summary": "Confirm the number for this invitation", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "maxLength": 32 }, "noNumber": { "type": "boolean", "enum": [ true ] }, "whatsappPhone": { "type": "string", "maxLength": 32 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Phone confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "confirmed": { "type": "boolean" } }, "required": [ "confirmed" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/phone/reset": { "post": { "operationId": "resetQuickLinkPhone", "tags": [ "QuickLink" ], "security": [], "summary": "Return to phone entry before connecting", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Phone entry restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "confirmed": { "type": "boolean" } }, "required": [ "confirmed" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/connection": { "post": { "operationId": "selectQuickLinkConnection", "tags": [ "QuickLink" ], "security": [], "summary": "Select an allowed connection type", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "string", "enum": [ "cloud", "linked" ] } }, "required": [ "connection" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Selected", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connection": { "type": "string", "enum": [ "cloud", "linked" ] } }, "required": [ "connection" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/cloud": { "post": { "operationId": "completeQuickLinkCloudSignup", "tags": [ "QuickLink" ], "security": [], "summary": "Advance Cloud onboarding", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/EmbeddedSignupResult" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Onboarding progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stage": { "type": "string" } }, "required": [ "stage" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/history": { "post": { "operationId": "chooseQuickLinkHistory", "tags": [ "QuickLink" ], "security": [], "summary": "Choose history sharing before connecting", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "historySync": { "type": "boolean" } }, "required": [ "historySync" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "History choice recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuickLinkState" } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/testing": { "patch": { "operationId": "customizeQuickLinkTesting", "tags": [ "QuickLink" ], "security": [], "summary": "Customize a simulated QuickLink account", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "maxLength": 139 } }, "additionalProperties": false }, "accountType": { "type": "string", "enum": [ "personal", "business" ] }, "replyBehavior": { "type": "string", "enum": [ "off", "echo" ] }, "failureScenario": { "type": "string", "enum": [ "none", "reject-send" ] }, "historyFixtureId": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Test configuration updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuickLinkState" } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/testing/start": { "post": { "operationId": "startQuickLinkTesting", "tags": [ "QuickLink" ], "security": [], "summary": "Start the simulated account reserved by a QuickLink", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Current test connection state", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuickLinkState" } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}": { "get": { "operationId": "getQuickLinkState", "tags": [ "QuickLink" ], "security": [], "summary": "Read QuickLink state", "description": "Returns the hosted page state for a QuickLink. Public; the token in the URL is the credential. Starts linked-device pairing after an allowed connection type has been selected.", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Current QuickLink state", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuickLinkState" } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/logo": { "get": { "operationId": "getQuickLinkLogo", "tags": [ "QuickLink" ], "security": [], "summary": "Read the QuickLink page logo", "description": "Returns the saved logo image for the page. Public; the token in the URL is the credential.", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Logo image", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/code": { "post": { "operationId": "requestQuickLinkCode", "tags": [ "QuickLink" ], "security": [], "summary": "Request a QuickLink pairing code", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickLinkCodeRequest" } } } }, "responses": { "200": { "description": "Pairing code issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "code", "phone" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "402": { "description": "The team cannot fund pairing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/confirm": { "post": { "operationId": "confirmQuickLink", "tags": [ "QuickLink" ], "security": [], "summary": "Confirm a linked QuickLink", "description": "Records consent, applies the chat-history choice, assigns Customer ownership when applicable, and returns the redirect target.", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickLinkConfirmRequest" } } } }, "responses": { "200": { "description": "Connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "connected" ] }, "phone": { "type": "string", "nullable": true }, "historySync": { "type": "boolean" }, "redirectUrl": { "type": "string", "nullable": true } }, "required": [ "status", "phone", "historySync", "redirectUrl" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/quicklink/{token}/cancel": { "post": { "operationId": "cancelQuickLinkByToken", "tags": [ "QuickLink" ], "security": [], "summary": "Cancel a QuickLink from the hosted page", "parameters": [ { "schema": { "type": "string", "description": "Opaque QuickLink token from the hosted URL." }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cancelled" ] }, "redirectUrl": { "type": "string", "nullable": true } }, "required": [ "status", "redirectUrl" ] } }, "required": [ "data" ] } } } }, "202": { "description": "QuickLink invalidated; Number cleanup pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cancelled" ] }, "redirectUrl": { "type": "string", "nullable": true } }, "required": [ "status", "redirectUrl" ] } }, "required": [ "data" ] } } } }, "400": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "403": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "404": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "409": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "422": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "429": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "500": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } }, "503": { "description": "QuickLink request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuickLinkError" } } } } } } }, "/messaging/cloud-api/embedded-signup": { "post": { "operationId": "embeddedSignup", "tags": [ "Cloud API" ], "summary": "Advance Meta Cloud API setup for an issued QuickLink", "security": [ { "BearerAuth": [] } ], "x-required-scope": "quicklink:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedSignupRequest" } } } }, "responses": { "200": { "description": "Onboarding progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "stage": { "type": "string" } }, "required": [ "stage" ] } }, "required": [ "success", "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request — request body or params failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "authentication_error", "code": "invalid_credential", "message": "Supply a valid credential.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-credential" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Authenticated but not permitted (missing scope or rule violation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "410": { "description": "Direct session signup was retired; create a QuickLink first", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_gone", "message": "The requested retained resource has expired or was removed.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-gone" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected service failure occurred. Keep the request ID for support.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#internal-error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "x-mint": { "content": "quicklink:manage" }, "description": "**Required scope:** `quicklink:manage`" } }, "/messaging/projects/{projectId}/test-history-fixtures": { "post": { "operationId": "createTestingHistoryFixture", "tags": [ "Testing" ], "security": [ { "BearerAuth": [] } ], "x-required-scope": "sandbox:write", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "senderPhone": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$" }, "text": { "type": "string", "maxLength": 4096 }, "timestamp": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "fromMe": { "type": "boolean" } }, "required": [ "id", "senderPhone", "text", "timestamp", "fromMe" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "messages" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Project-scoped history fixture", "content": { "application/json": { "schema": { "type": "object", "properties": { "fixtureId": { "type": "string", "format": "uuid" } }, "required": [ "fixtureId" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } } }, "400": { "description": "Invalid fixture", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } } }, "403": { "description": "Test access required", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } }, "404": { "description": "Project not found", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } } }, "502": { "description": "Test runtime unavailable", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } } } }, "x-mint": { "content": "sandbox:write" }, "description": "**Required scope:** `sandbox:write`" } }, "/messaging/test-events/fixtures": { "get": { "operationId": "listTestEventFixtures", "tags": [ "Testing" ], "security": [ { "BearerAuth": [] } ], "summary": "List test event fixtures", "x-required-scope": "sandbox:read", "responses": { "200": { "description": "Available fixtures and the overrides each accepts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTestEventFixtureList" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } } }, "403": { "description": "Read scope required; client tokens are not permitted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } } }, "x-mint": { "content": "sandbox:read" }, "description": "**Required scope:** `sandbox:read`" } }, "/messaging/{session}/test-events": { "post": { "operationId": "triggerTestEvent", "tags": [ "Testing" ], "security": [ { "BearerAuth": [] } ], "summary": "Trigger a test event for a Test number", "x-required-scope": "sandbox:write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Test Number ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,255}$", "description": "Optional. Repeating a request with the same key and body reuses the same event ID, so a retry after a failed or uncertain response never creates a second event or duplicate webhook deliveries." }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTriggerTestEventRequest" } } } }, "responses": { "202": { "description": "Test event accepted for delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTriggerTestEventResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } } }, "400": { "description": "Invalid fixture or override", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } } }, "403": { "description": "Test numbers access required, or a client token was used", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } }, "404": { "description": "Resource not found", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } } }, "429": { "description": "Test event rate limit reached", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } } }, "502": { "description": "Test event delivery unavailable. Retry with the same Idempotency-Key to avoid a second event.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } } } }, "x-mint": { "content": "Linked Device API sandbox:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sandbox:write`" } }, "/messaging/{session}/phone": { "get": { "operationId": "getTestingPhone", "tags": [ "Testing" ], "security": [ { "BearerAuth": [] } ], "summary": "Get a Test number's phone", "x-required-scope": "sandbox:read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The Test number's session ID." }, "required": true, "name": "session", "in": "path" } ], "responses": { "200": { "description": "The simulated phone and its linked companions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTestingPhoneState" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } } }, "403": { "description": "Test numbers access required, or a client token was used", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } }, "404": { "description": "Resource not found", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } } }, "502": { "description": "The simulated phone could not be read. Retry later.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } } } }, "x-mint": { "content": "Linked Device API sandbox:read" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sandbox:read`" } }, "/messaging/{session}/phone/messages": { "post": { "operationId": "sendTestingPhoneMessage", "tags": [ "Testing" ], "security": [ { "BearerAuth": [] } ], "summary": "Send a message from a Test number's phone", "x-required-scope": "sandbox:write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The Test number's session ID." }, "required": true, "name": "session", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTestingPhoneMessageRequest" } } } }, "responses": { "202": { "description": "The phone sent the message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTestingPhoneMessage" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } } }, "400": { "description": "Invalid recipient, or the phone is offline", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } } }, "403": { "description": "Test numbers access required, or a client token was used", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } }, "404": { "description": "Resource not found", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } } }, "429": { "description": "Testing rate limit reached", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "The request limit was reached. Follow Retry-After when supplied.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded" } } } }, "502": { "description": "The phone could not send the message. Retry later.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } } } }, "x-mint": { "content": "Linked Device API sandbox:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sandbox:write`" } }, "/messaging/{session}/phone/devices/{deviceId}/unlink": { "post": { "operationId": "unlinkTestingPhoneDevice", "tags": [ "Testing" ], "security": [ { "BearerAuth": [] } ], "summary": "Unlink a companion from a Test number's phone", "x-required-scope": "sandbox:write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The Test number's session ID." }, "required": true, "name": "session", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 99, "description": "The companion's device ID, as listed by the phone." }, "required": true, "name": "deviceId", "in": "path" } ], "responses": { "200": { "description": "The companion was unlinked and logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinTestingPhoneUnlink" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } } }, "400": { "description": "The phone is offline", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Correct the invalid request field.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter" } } } }, "403": { "description": "Test numbers access required, or a client token was used", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "permission_error", "code": "permission_denied", "message": "The credential does not have access to this resource.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#permission-denied" } } } }, "404": { "description": "Project or companion not found", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The resource is unavailable to this caller.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#resource-not-found" } } } }, "502": { "description": "The phone could not unlink the companion. Retry later.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/TestDropinX-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/TestDropinX-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/TestDropinX-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDropinPublicError" }, "example": { "error": { "type": "upstream_error", "code": "upstream_failure", "message": "The messaging provider could not complete the request.", "param": null, "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30" }, "data": null, "docs": "https://docs.polymorfa.com/api/errors#upstream-failure" } } } } }, "x-mint": { "content": "Linked Device API sandbox:write" }, "x-protocols": [ "Linked Device API" ], "description": "**Protocols:** Linked Device API\n\n**Required scope:** `sandbox:write`" } } }, "x-webhooks": { "message.received": { "post": { "operationId": "onMessageReceived", "summary": "Incoming message", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageReceivedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.sent": { "post": { "operationId": "onMessageSent", "summary": "Outgoing message successfully sent", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSentEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.ack": { "post": { "operationId": "onMessageAck", "summary": "Delivery acknowledgement", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageAckEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.revoked": { "post": { "operationId": "onMessageRevoked", "summary": "Message revoked", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRevokedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.reaction": { "post": { "operationId": "onMessageReaction", "summary": "Reaction added or removed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageReactionEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.edited": { "post": { "operationId": "onMessageEdited", "summary": "Message edited", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEditedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.update": { "post": { "operationId": "onMessageUpdate", "summary": "Generic message update", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.delete": { "post": { "operationId": "onMessageDelete", "summary": "Message deleted from another device", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDeleteEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.vote": { "post": { "operationId": "onMessageVote", "summary": "Poll vote cast", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageVoteEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "session.status": { "post": { "operationId": "onSessionStatus", "summary": "Session status change", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatusEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "session.connected": { "post": { "operationId": "onSessionConnected", "summary": "Session connected to WhatsApp", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionConnectedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "session.logged_out": { "post": { "operationId": "onSessionLoggedOut", "summary": "Session logged out", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionLoggedOutEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "session.phone_offline": { "post": { "operationId": "onSessionPhoneOffline", "summary": "Primary phone has been offline for an extended period", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPhoneOfflineEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "session.restriction_updated": { "post": { "operationId": "onSessionRestrictionUpdated", "summary": "A WhatsApp restriction on the number started, changed or ended", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRestrictionUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "group.update": { "post": { "operationId": "onGroupUpdate", "summary": "Group metadata changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "group.participant": { "post": { "operationId": "onGroupParticipant", "summary": "Group participants added/removed/promoted/demoted", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupParticipantEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "presence.update": { "post": { "operationId": "onPresenceUpdate", "summary": "User or chat presence change", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "contact.update": { "post": { "operationId": "onContactUpdate", "summary": "Contact info changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "contact.opted_out": { "post": { "operationId": "onContactOptedOut", "summary": "A contact opted out of campaigns by replying with an opt-out keyword", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactOptedOutEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "contact.opted_in": { "post": { "operationId": "onContactOptedIn", "summary": "A contact reversed a keyword opt-out by replying with an opt-in keyword", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactOptedInEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "chat.archive": { "post": { "operationId": "onChatArchive", "summary": "Chat archived or pinned", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatArchiveEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "chat.mute": { "post": { "operationId": "onChatMute", "summary": "Chat muted or unmuted", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMuteEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "chat.read": { "post": { "operationId": "onChatRead", "summary": "Chat marked read or unread", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatReadEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "chat.clear": { "post": { "operationId": "onChatClear", "summary": "Chat cleared", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatClearEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "chat.delete": { "post": { "operationId": "onChatDelete", "summary": "Chat deleted", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatDeleteEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.received": { "post": { "operationId": "onCallReceived", "summary": "Incoming call", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallReceivedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.missed": { "post": { "operationId": "onCallMissed", "summary": "Call missed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallMissedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.accepted": { "post": { "operationId": "onCallAccepted", "summary": "Call accepted", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallAcceptedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.rejected": { "post": { "operationId": "onCallRejected", "summary": "Call rejected", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallRejectedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.ended": { "post": { "operationId": "onCallEnded", "summary": "Call ended", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallEndedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.telemetry": { "post": { "operationId": "onCallTelemetry", "summary": "Call telemetry", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallTelemetryEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.participant_joined": { "post": { "operationId": "onCallParticipantJoined", "summary": "Participant joined a call", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallParticipantJoinedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.participant_state": { "post": { "operationId": "onCallParticipantState", "summary": "Participant call state changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallParticipantStateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.participant_left": { "post": { "operationId": "onCallParticipantLeft", "summary": "Participant left a call", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallParticipantLeftEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.connection_joined": { "post": { "operationId": "onCallConnectionJoined", "summary": "Connection joined a call", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallConnectionJoinedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.permission_changed": { "post": { "operationId": "onCallPermissionChanged", "summary": "Call permission changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallPermissionChangedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "call.connection_left": { "post": { "operationId": "onCallConnectionLeft", "summary": "Connection left a call", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallConnectionLeftEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "usage.recorded": { "post": { "operationId": "onUsageRecorded", "summary": "Usage recorded", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecordedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "newsletter.update": { "post": { "operationId": "onNewsletterUpdate", "summary": "Newsletter subscription change", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "blocklist.update": { "post": { "operationId": "onBlocklistUpdate", "summary": "Blocklist changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlocklistUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "labels.update": { "post": { "operationId": "onLabelsUpdate", "summary": "Label edited / associated / star toggled", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelsUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "business.quick_reply.update": { "post": { "operationId": "onBusinessQuickReplyUpdate", "summary": "WhatsApp Business App quick reply changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessQuickReplyUpdateEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "contact.sync": { "post": { "operationId": "onContactSync", "summary": "WhatsApp Business app contact synchronization", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsSyncEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.echo": { "post": { "operationId": "onMessageEcho", "summary": "Message sent from the WhatsApp Business app", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEchoEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "history.sync": { "post": { "operationId": "onHistorySync", "summary": "History sync chunk", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistorySyncEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "command.result": { "post": { "operationId": "onCommandResult", "summary": "Async command completed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandResultEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.enabled": { "post": { "operationId": "onCustomerEnabled", "summary": "Customers enabled for a project", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEnabledEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.created": { "post": { "operationId": "onCustomerCreated", "summary": "Customer created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.updated": { "post": { "operationId": "onCustomerUpdated", "summary": "Customer updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.archiving": { "post": { "operationId": "onCustomerArchiving", "summary": "Customer archival started", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerArchivingEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.archived": { "post": { "operationId": "onCustomerArchived", "summary": "Customer archived", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerArchivedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.restored": { "post": { "operationId": "onCustomerRestored", "summary": "Customer restored", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRestoredEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.pairing_link.created": { "post": { "operationId": "onCustomerPairingLinkCreated", "summary": "Customer pairing link created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPairingLinkCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.pairing_link.opened": { "post": { "operationId": "onCustomerPairingLinkOpened", "summary": "Customer pairing link opened", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPairingLinkOpenedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.pairing_link.connected": { "post": { "operationId": "onCustomerPairingLinkConnected", "summary": "Customer pairing link connected", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPairingLinkConnectedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.pairing_link.failed": { "post": { "operationId": "onCustomerPairingLinkFailed", "summary": "Customer pairing attempt failed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPairingLinkFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.pairing_link.expired": { "post": { "operationId": "onCustomerPairingLinkExpired", "summary": "Customer pairing link expired", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPairingLinkExpiredEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.pairing_link.revoked": { "post": { "operationId": "onCustomerPairingLinkRevoked", "summary": "Customer pairing link revoked", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPairingLinkRevokedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.number.attached": { "post": { "operationId": "onCustomerNumberAttached", "summary": "Number attached to a Customer", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNumberAttachedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.number.transferred": { "post": { "operationId": "onCustomerNumberTransferred", "summary": "Number transferred to a Customer", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNumberTransferredEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "customer.number.disconnected": { "post": { "operationId": "onCustomerNumberDisconnected", "summary": "Customer Number disconnected", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNumberDisconnectedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "voice.asset_ready": { "post": { "operationId": "onVoiceAssetReady", "summary": "Audio asset ready", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceAssetReadyEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "voice.asset_failed": { "post": { "operationId": "onVoiceAssetFailed", "summary": "Audio asset failed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceAssetFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "bansafe.action": { "post": { "operationId": "onBansafeAction", "summary": "Polymorfa applied, changed, or lifted a safety restriction on a number", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanSafeActionEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "bansafe.health_threshold": { "post": { "operationId": "onBansafeHealthThreshold", "summary": "A project's present Health rule crossed below its threshold", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanSafeHealthThresholdEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "bansafe.incident": { "post": { "operationId": "onBansafeIncident", "summary": "A restriction was recorded on a number, or the record of one settled", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanSafeIncidentEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "bansafe.claim": { "post": { "operationId": "onBansafeClaim", "summary": "A Ban Insurance claim was filed on a ban, decided, paid, or reversed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanSafeClaimEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "message.failed": { "post": { "operationId": "onMessageFailed", "summary": "Outbound send failed, including a send refused by safety", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "template.status": { "post": { "operationId": "onTemplateStatus", "summary": "Message template approval status changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateStatusEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "order.payment_updated": { "post": { "operationId": "onOrderPaymentUpdated", "summary": "WhatsApp reported a payment update for an order", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.paused": { "post": { "operationId": "onCampaignPaused", "summary": "Campaign paused", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPausedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.launched": { "post": { "operationId": "onCampaignLaunched", "summary": "Campaign began sending", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLaunchedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.resumed": { "post": { "operationId": "onCampaignResumed", "summary": "Campaign resumed sending", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResumedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.stopped": { "post": { "operationId": "onCampaignStopped", "summary": "Campaign stop settled", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStoppedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.rescheduled": { "post": { "operationId": "onCampaignRescheduled", "summary": "A scheduled campaign's start time moved", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRescheduledEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.completed": { "post": { "operationId": "onCampaignCompleted", "summary": "Campaign finished sending", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCompletedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.failed": { "post": { "operationId": "onCampaignFailed", "summary": "Campaign failed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.recipient_sent": { "post": { "operationId": "onCampaignRecipientSent", "summary": "A campaign recipient was sent", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientSentEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.recipient_failed": { "post": { "operationId": "onCampaignRecipientFailed", "summary": "A campaign recipient failed after its last attempt", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.recipient_skipped": { "post": { "operationId": "onCampaignRecipientSkipped", "summary": "A campaign recipient was skipped", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientSkippedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.throttled": { "post": { "operationId": "onCampaignThrottled", "summary": "Campaign sending was paced", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignThrottledEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.cap_reached": { "post": { "operationId": "onCampaignCapReached", "summary": "A sending number reached its hourly or daily cap", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCapReachedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } }, "campaign.cold_blocked": { "post": { "operationId": "onCampaignColdBlocked", "summary": "A campaign recipient was held because they never wrote first", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignColdBlockedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Non-2xx responses are retried according to the retry policy." } } } } } }