{ "openapi": "3.1.0", "info": { "title": "QuiC Platform API", "version": "2026-10-01", "description": "Message QuiC users who opted in to your app. No message is ever delivered without the user's opt-in. Business chats are NOT end-to-end encrypted. Free during the preview; rate limits and quotas apply." }, "servers": [ { "url": "https://api.quic.chat/platform/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Messages" }, { "name": "Media" }, { "name": "Users & consent" }, { "name": "Business profile" }, { "name": "Diagnostics" } ], "paths": { "/ping": { "get": { "summary": "Check a key", "tags": [ "Diagnostics" ], "responses": { "200": { "description": "Key is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "appId": { "type": "string" }, "appStatus": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "messages:send", "messages:read", "media:write", "consents:read", "optin_links:create", "profile:write", "webhooks:manage", "templates:manage" ] } }, "apiVersion": { "type": "string" }, "requestId": { "type": "string" }, "time": { "type": "string", "format": "date-time" } }, "required": [ "ok", "appId", "appStatus", "environment", "scopes", "apiVersion", "requestId", "time" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages": { "post": { "summary": "Send a message", "description": "Queues a text or media message to a user who opted in. Sandbox keys reach accepted testers only; internal_live apps reach their own organization (and may address by work email with a live key); public_live apps reach any organization that allows external businesses. Outside the 24h window after the user's last message an app may send at most 3 messages per user per 24h.", "tags": [ "Messages" ], "x-quic-scope": "messages:send", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. Any unique string (<=255 printable ASCII). Kept 24h: same key + same body replays the first response; same key + different body is 422.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "oneOf": [ { "type": "object", "properties": { "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" } }, "required": [ "appUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "internal_live apps with a live key only (D4)" } }, "required": [ "email" ], "additionalProperties": false } ] }, "type": { "type": "string", "enum": [ "text", "image", "video", "audio", "file" ] }, "text": { "type": "string", "maxLength": 4096, "description": "Required for text; caption for media" }, "mediaId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "From POST /media; required for media types" }, "clientReference": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Echoed in message.status events" } }, "required": [ "to", "type" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "const": "accepted", "type": "string" }, "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "type": { "type": "string", "enum": [ "text", "image", "video", "audio", "file" ] }, "createdAt": { "type": "string", "format": "date-time" }, "clientReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "appUserId", "type", "createdAt", "clientReference" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/{id}": { "get": { "summary": "Get a message", "tags": [ "Messages" ], "x-quic-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "Message id" } ], "responses": { "200": { "description": "The message", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "appUserId": { "anyOf": [ { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, { "type": "null" } ], "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "type": { "type": "string" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fileName": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "id", "mimeType", "fileName", "size" ] } }, "status": { "type": "string", "enum": [ "sent", "delivered", "read", "received" ] }, "clientReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "direction", "appUserId", "type", "text", "media", "status", "clientReference", "createdAt", "deliveredAt", "readAt" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/media": { "post": { "summary": "Create an upload", "description": "Returns a presigned PUT URL. Upload the bytes with the same Content-Type within 15 minutes, then reference media.id in POST /messages. Images, video and audio up to 16 MB; documents up to 100 MB. 100 uploads per hour.", "tags": [ "Media" ], "x-quic-scope": "media:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif", "video/mp4", "video/3gpp", "video/quicktime", "audio/mpeg", "audio/mp4", "audio/aac", "audio/ogg", "audio/amr", "application/pdf", "text/plain", "text/csv", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.presentationml.presentation" ] }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 104857600, "description": "Bytes. Images/video/audio <= 16 MB, documents <= 100 MB" } }, "required": [ "fileName", "mimeType", "size" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Upload created", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "app", "user" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "document", "other" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending_upload", "ready" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Presigned download URL, valid 1 hour" }, "urlExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "source", "kind", "mimeType", "fileName", "size", "status", "url", "urlExpiresAt", "createdAt" ] }, "upload": { "type": "object", "properties": { "url": { "type": "string", "description": "PUT the bytes here within 15 minutes" }, "method": { "const": "PUT", "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "url", "method", "headers", "expiresAt" ] } }, "required": [ "media", "upload" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/media/{id}": { "get": { "summary": "Get media", "description": "Your uploads, or media a user sent you (message.received media ids). Returns a 1-hour download URL.", "tags": [ "Media" ], "x-quic-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "Media id" } ], "responses": { "200": { "description": "The media", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "app", "user" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "document", "other" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending_upload", "ready" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Presigned download URL, valid 1 hour" }, "urlExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "source", "kind", "mimeType", "fileName", "size", "status", "url", "urlExpiresAt", "createdAt" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{appUserId}": { "get": { "summary": "Get a user's consent + window", "tags": [ "Users & consent" ], "x-quic-scope": "consents:read", "parameters": [ { "name": "appUserId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "Per-app user id" } ], "responses": { "200": { "description": "The user", "content": { "application/json": { "schema": { "type": "object", "properties": { "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "consent": { "type": "object", "properties": { "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "status": { "type": "string", "enum": [ "opted_in", "opted_out", "blocked" ] }, "source": { "type": "string", "enum": [ "user_initiated", "profile_allow", "opt_in_link", "sandbox_tester" ] }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optedInAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "optedOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "appUserId", "status", "source", "ref", "optedInAt", "optedOutAt", "updatedAt" ] }, "window": { "type": "object", "properties": { "open": { "type": "boolean", "description": "true within 24h of the user's last message" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "open", "expiresAt" ] } }, "required": [ "appUserId", "consent", "window" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consents": { "get": { "summary": "List consents", "tags": [ "Users & consent" ], "x-quic-scope": "consents:read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "opted_in", "opted_out", "blocked" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "A page of consents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "status": { "type": "string", "enum": [ "opted_in", "opted_out", "blocked" ] }, "source": { "type": "string", "enum": [ "user_initiated", "profile_allow", "opt_in_link", "sandbox_tester" ] }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optedInAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "optedOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "appUserId", "status", "source", "ref", "optedInAt", "optedOutAt", "updatedAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/optin-links": { "post": { "summary": "Create an opt-in link", "description": "A signed link to your business profile. Opening it never opts the user in; they must tap Allow in QuiC. The ref comes back in consent.updated.", "tags": [ "Users & consent" ], "x-quic-scope": "optin_links:create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,64}$", "description": "Your own reference, echoed in consent.updated" }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 90 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "token": { "type": "string" }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "url", "token", "ref", "expiresAt" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business-profile": { "get": { "summary": "Get your business profile", "tags": [ "Business profile" ], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "handle": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "about": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verificationStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "revoked" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "appId", "handle", "displayName", "avatarUrl", "about", "websiteUrl", "domain", "category", "verificationStatus", "verifiedAt", "updatedAt" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update your business profile", "tags": [ "Business profile" ], "x-quic-scope": "profile:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 2, "maxLength": 60 }, "about": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "avatarMediaId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "A ready image from POST /media, <= 5 MB" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "handle": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "about": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verificationStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "revoked" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "appId", "handle", "displayName", "avatarUrl", "about", "websiteUrl", "domain", "category", "verificationStatus", "verifiedAt", "updatedAt" ] } } } }, "400": { "description": "invalid_request / invalid_json / idempotency_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_in_progress / media_not_uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused / media_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "message.received": { "post": { "summary": "message.received event", "description": "Signed with QuiC-Signature: t=,v1=. Headers also carry QuiC-Event-Id and QuiC-Event-Type. Reject timestamps more than 5 minutes off and dedupe on the event id. Answer 2xx within 10s.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; dedupe on this" }, "type": { "const": "message.received", "type": "string" }, "apiVersion": { "type": "string" }, "created": { "type": "integer", "description": "Unix seconds" }, "appId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "type": { "type": "string" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "GET /media/:id" }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fileName": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "id", "mimeType", "fileName", "size" ] } }, "context": { "type": "object", "properties": { "messageId": { "type": "string" } }, "required": [ "messageId" ], "description": "Present when the user replied to a message" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "from", "type", "text", "media", "timestamp" ] } }, "required": [ "id", "type", "apiVersion", "created", "appId", "data" ] } } } }, "responses": { "200": { "description": "Acknowledged" } } } }, "message.status": { "post": { "summary": "message.status event", "description": "Signed with QuiC-Signature: t=,v1=. Headers also carry QuiC-Event-Id and QuiC-Event-Type. Reject timestamps more than 5 minutes off and dedupe on the event id. Answer 2xx within 10s.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; dedupe on this" }, "type": { "const": "message.status", "type": "string" }, "apiVersion": { "type": "string" }, "created": { "type": "integer", "description": "Unix seconds" }, "appId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "status": { "type": "string", "enum": [ "sent", "delivered", "read", "failed" ] }, "timestamp": { "type": "string", "format": "date-time" }, "clientReference": { "type": "string" } }, "required": [ "id", "appUserId", "status", "timestamp" ] } }, "required": [ "id", "type", "apiVersion", "created", "appId", "data" ] } } } }, "responses": { "200": { "description": "Acknowledged" } } } }, "consent.updated": { "post": { "summary": "consent.updated event", "description": "Signed with QuiC-Signature: t=,v1=. Headers also carry QuiC-Event-Id and QuiC-Event-Type. Reject timestamps more than 5 minutes off and dedupe on the event id. Answer 2xx within 10s.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; dedupe on this" }, "type": { "const": "consent.updated", "type": "string" }, "apiVersion": { "type": "string" }, "created": { "type": "integer", "description": "Unix seconds" }, "appId": { "type": "string" }, "data": { "type": "object", "properties": { "appUserId": { "type": "string", "pattern": "^u_[0-9A-Za-z]{22}$", "description": "Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz" }, "status": { "type": "string", "enum": [ "opted_in", "opted_out", "blocked" ] }, "source": { "type": "string", "enum": [ "user_initiated", "profile_allow", "opt_in_link", "sandbox_tester" ] }, "ref": { "type": "string", "description": "The opt-in link ref, for source opt_in_link" }, "reason": { "type": "string", "enum": [ "account_deleted" ] } }, "required": [ "appUserId", "status" ] } }, "required": [ "id", "type", "apiVersion", "created", "appId", "data" ] } } } }, "responses": { "200": { "description": "Acknowledged" } } } }, "app.status_changed": { "post": { "summary": "app.status_changed event", "description": "Signed with QuiC-Signature: t=,v1=. Headers also carry QuiC-Event-Id and QuiC-Event-Type. Reject timestamps more than 5 minutes off and dedupe on the event id. Answer 2xx within 10s.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; dedupe on this" }, "type": { "const": "app.status_changed", "type": "string" }, "apiVersion": { "type": "string" }, "created": { "type": "integer", "description": "Unix seconds" }, "appId": { "type": "string" }, "data": { "type": "object", "properties": { "status": { "type": "string" }, "previousStatus": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "status", "previousStatus" ] } }, "required": [ "id", "type", "apiVersion", "created", "appId", "data" ] } } } }, "responses": { "200": { "description": "Acknowledged" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key: qk_sb_… (sandbox) or qk_live_… (live). Scopes: messages:send, messages:read, media:write, consents:read, optin_links:create, profile:write, webhooks:manage, templates:manage." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "conflict_error", "idempotency_error", "rate_limit_error", "api_error" ] }, "requestId": { "type": "string" }, "docUrl": { "type": "string" }, "details": {} }, "required": [ "code", "message", "type", "requestId", "docUrl" ] } }, "required": [ "error" ] } } } }