{ "openapi": "3.1.0", "info": { "title": "Mandai API", "version": "0.1.0", "description": "Evidence-based transactional SMS API. Production and sandbox expose the same resource paths on isolated infrastructure." }, "servers": [ { "url": "https://api.mandaionline.com", "description": "Production" }, { "url": "https://sandbox.api.mandaionline.com", "description": "Customer sandbox" } ], "tags": [ { "name": "Infrastructure" }, { "name": "Authentication" }, { "name": "Tenancy" }, { "name": "API keys" }, { "name": "Messages" }, { "name": "Recipient automation" } ], "paths": { "/v1/health/live": { "get": { "operationId": "getLiveness", "summary": "Process liveness", "description": "Check whether the API Worker process can serve requests without accessing customer data or sending an SMS.", "tags": ["Infrastructure"], "x-mandai-requirements": ["API-001"], "responses": { "200": { "description": "The Worker process can serve requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/health/ready": { "get": { "operationId": "getReadiness", "summary": "Required dependency readiness", "description": "Checks D1 readiness without making a synchronous provider request or exposing dependency details.", "tags": ["Infrastructure"], "x-mandai-requirements": ["API-001"], "responses": { "200": { "description": "Required dependencies are ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } }, "503": { "description": "A required dependency is unavailable. Internal details are omitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableResponse" } } } } } } }, "/v1/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "Return the released OpenAPI contract", "description": "Return the released OpenAPI contract.", "tags": ["Infrastructure"], "x-mandai-requirements": ["API-008"], "responses": { "200": { "description": "The immutable contract snapshot for this release.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/console/auth/google/start": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "get": { "operationId": "startGoogleLogin", "summary": "Start direct Google authorization-code flow", "description": "Creates single-use state, nonce, browser binding, and a PKCE S256 challenge before redirecting directly to Google.", "tags": ["Authentication"], "x-mandai-requirements": ["AUTH-001", "AUTH-002", "AUTH-003"], "parameters": [ { "name": "client", "in": "query", "required": false, "description": "Selects the allowlisted post-login client. Omit for the customer console; use admin_desktop only for the local operator application.", "schema": { "type": "string", "enum": ["admin_desktop"] } } ], "responses": { "302": { "description": "Redirect to Google's authorization endpoint.", "headers": { "Location": { "required": true, "schema": { "type": "string", "format": "uri" } }, "Set-Cookie": { "required": true, "schema": { "type": "string" }, "description": "Short-lived hardened browser-binding cookie; no Google credential is stored in it." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationProblem" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } } } }, "/v1/console/auth/google/callback": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "get": { "operationId": "completeGoogleLogin", "summary": "Complete Google login and create a Mandai session", "description": "Consumes the single-use OAuth transaction, exchanges the code server-side, verifies the ID token, and redirects without exposing Google tokens.", "tags": ["Authentication"], "x-mandai-requirements": ["AUTH-003", "AUTH-004", "AUTH-005", "AUTH-006", "AUTH-007", "AUTH-011"], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Mandai session created; redirect to the configured console URL without OAuth query parameters.", "headers": { "Location": { "required": true, "schema": { "type": "string", "format": "uri" } }, "Set-Cookie": { "required": true, "schema": { "type": "string" }, "description": "Opaque HttpOnly session cookie and separate CSRF cookie." } } }, "400": { "$ref": "#/components/responses/InvalidAuthentication" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdentityConflict" } } } }, "/v1/console/session": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "get": { "operationId": "getSession", "summary": "Return the current Mandai browser session", "description": "Return the current Mandai browser session. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Authentication"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-007", "AUTH-009"], "responses": { "200": { "description": "Current session, tenant, role, and CSRF metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/console/session/workspace": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "put": { "operationId": "switchActiveWorkspace", "summary": "Switch the server-side session to another authorized workspace", "description": "Switch the server-side session to another authorized workspace. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Authentication", "Tenancy"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "ACCT-005"], "parameters": [{ "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchWorkspaceRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "200": { "description": "Session rebound to an existing membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/console/auth/logout": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "post": { "operationId": "logout", "summary": "Revoke the current server-side session", "description": "Revoke the current server-side session. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Authentication"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-007", "AUTH-008", "AUTH-009"], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 32 }, "description": "Must match the CSRF cookie and server-side one-way value; Origin must also be allowed." } ], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Session revoked and browser cookies expired." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/console/members": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "get": { "operationId": "listWorkspaceMembers", "summary": "List members and pending invitations in the active workspace", "description": "List members and pending invitations in the active workspace. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Tenancy"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-009", "AUTH-010", "ACCT-005"], "responses": { "200": { "description": "Tenant-scoped members and invitations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/console/members/invitations": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "post": { "operationId": "inviteWorkspaceMember", "summary": "Create or refresh an email-bound workspace invitation", "description": "Create or refresh an email-bound workspace invitation. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Tenancy"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "AUTH-010", "ACCT-005"], "parameters": [{ "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "201": { "description": "Invitation created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/console/members/{membership_id}/role": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "put": { "operationId": "updateWorkspaceMemberRole", "summary": "Update a member role within the active workspace", "description": "Update a member role within the active workspace. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Tenancy"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "AUTH-010", "ACCT-005"], "parameters": [{ "$ref": "#/components/parameters/CsrfToken" }, { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Role updated." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/console/members/{membership_id}": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "delete": { "operationId": "removeWorkspaceMember", "summary": "Remove a member and revoke tenant-scoped sessions", "description": "Remove a member and revoke tenant-scoped sessions. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Tenancy"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "AUTH-010", "ACCT-005"], "parameters": [{ "$ref": "#/components/parameters/CsrfToken" }, { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Membership removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/console/me/onboarding-completion": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "post": { "operationId": "completeOnboarding", "summary": "Persist personal onboarding preferences", "description": "Idempotently stores the preferred display name and membership-scoped onboarding choices before the console is unlocked.", "tags": ["Tenancy"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "SBX-012"], "parameters": [{ "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteOnboardingRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "200": { "description": "Onboarding preferences persisted and workspace prepared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteOnboardingResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/console/e/{environment}/v1/api-keys": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "get": { "operationId": "listApiKeys", "summary": "List API-key metadata for the current environment", "description": "Administrator-only. Plaintext credentials and verification hashes are never returned.", "tags": ["API keys"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-009", "AUTH-010", "ACCT-003", "ACCT-004", "ACCT-005"], "responses": { "200": { "description": "Environment-scoped API-key metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createApiKey", "summary": "Create an environment- and capability-scoped API key", "description": "Administrator session, allowed Origin, and double-submit CSRF are required. The plaintext credential is revealed exactly once in this response.", "tags": ["API keys"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "AUTH-010", "ACCT-001", "ACCT-003", "ACCT-004", "ACCT-006", "ACCT-007"], "parameters": [{ "$ref": "#/components/parameters/SecretCommandKey" }, { "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "201": { "description": "Key created. The api_key value cannot be retrieved again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealedApiKeyResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationProblem" }, "422": { "$ref": "#/components/responses/ValidationProblem" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/console/e/{environment}/v1/api-keys/{key_id}/rotations": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "post": { "operationId": "rotateApiKey", "summary": "Rotate an API key with an explicit overlap window", "description": "Creates a replacement with the same capabilities, reveals only the new credential, and expires the previous key after the requested overlap.", "tags": ["API keys"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "AUTH-010", "ACCT-003", "ACCT-004", "ACCT-006"], "parameters": [{ "$ref": "#/components/parameters/SecretCommandKey" }, { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiKeyRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "201": { "description": "Replacement key created and revealed once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealedApiKeyResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationProblem" }, "422": { "$ref": "#/components/responses/ValidationProblem" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/console/e/{environment}/v1/api-keys/{key_id}": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Revoke an API key. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["API keys"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["AUTH-008", "AUTH-009", "AUTH-010", "ACCT-003", "ACCT-004", "ACCT-006"], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Key revoked." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/messages/preview": { "post": { "operationId": "previewMessage", "summary": "Validate a single SMS and estimate its maximum charge", "description": "Authenticates a messages:preview capability, validates Brazilian E.164 input, applies the 3GPP GSM default and extension alphabets or UCS-2, and returns a versioned R$0.13-per-segment maximum-charge estimate without message persistence or provider access.", "tags": ["Messages"], "security": [{ "mandaiApiKey": [] }], "x-mandai-requirements": ["SEND-001", "SEND-004", "SEND-005", "API-001"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePreviewRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "200": { "description": "The normalized destination and cost preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/messages": { "post": { "operationId": "createMessage", "summary": "Durably accept one immediate SMS intent", "description": "Requires the messages:send capability. Returns after the message intent and outbox record commit, not after provider acknowledgment or delivery. On the sandbox server, only the published non-routable recipients are accepted; results are simulated and non-billable. Production dispatch creates one immutable provider attempt; an ambiguous submission becomes unknown and is not automatically resent.", "tags": ["Messages"], "security": [{ "mandaiApiKey": [] }], "x-mandai-requirements": ["SEND-001", "SEND-002", "SEND-003", "SEND-008", "MSG-001", "API-001", "API-003"], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Tenant-, environment-, API-major-, and operation-scoped key retained for at least seven days. Equivalent replay returns the original resource; reuse with different semantic content returns a conflict.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "202": { "description": "The message intent and outbox command were committed.", "headers": { "Location": { "required": true, "schema": { "type": "string" }, "description": "Canonical URL of the created message." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/console/e/{environment}/v1/messages": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "get": { "operationId": "listConsoleMessages", "summary": "List recent environment-scoped message evidence", "description": "Returns up to 50 recent sanitized message summaries for the active tenant and environment. Recipients, message bodies, provider identifiers, metadata, and raw evidence are never included.", "tags": ["Messages"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["MSG-001", "MSG-002", "AUTH-008", "AUTH-009"], "responses": { "200": { "description": "Recent sanitized message summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSummaryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/messages/{messageId}": { "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "getMessageEvidence", "summary": "Get one message and its immutable evidence timeline", "description": "Requires messages:read. The lookup is scoped to the authenticated tenant and server environment. It never exposes the message body, recipient, encrypted values, provider identifiers, arbitrary metadata, or raw evidence.", "tags": ["Messages"], "security": [{ "mandaiApiKey": [] }], "x-mandai-requirements": ["MSG-001", "MSG-002", "AUTH-009", "API-001"], "responses": { "200": { "description": "The current message snapshot and ordered immutable events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEvidenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/reliability": { "get": { "operationId": "getReliabilityEvidence", "summary": "Get tenant-scoped route and delivery reliability evidence", "description": "Requires messages:read. Returns route, final-delivery rate, carrier breakdown when the route supplies a carrier, p95/p99 observed latencies, throughput, stability, sample limits, freshness, and the contractual service-level state. Provider acknowledgement is never counted as delivery.", "tags": ["Messages"], "security": [{ "mandaiApiKey": [] }], "x-mandai-requirements": ["MSG-001", "MSG-002", "AUTH-009", "API-001"], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": ["24h", "7d", "30d"], "default": "24h" } } ], "responses": { "200": { "description": "Observed reliability evidence for the authenticated tenant and current environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReliabilityResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/console/e/{environment}/v1/messages/{messageId}": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [ { "$ref": "#/components/parameters/ConsoleEnvironment" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "getConsoleMessageEvidence", "summary": "Get one environment-scoped message timeline in the console", "description": "Get one environment-scoped message timeline in the console. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Messages"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["MSG-001", "MSG-002", "AUTH-008", "AUTH-009"], "responses": { "200": { "description": "The sanitized message evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEvidenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/console/e/{environment}/v1/messages/{messageId}/receipt-inspections": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [ { "$ref": "#/components/parameters/ConsoleEnvironment" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" } } ], "post": { "operationId": "confirmMessageReceiptInspection", "summary": "Confirm that the authenticated user inspected a receipt", "description": "Requires messages:read and the same-origin CSRF boundary. The command is idempotent for one user and message.", "tags": ["Messages"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["MSG-002", "AUTH-008", "AUTH-009"], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Inspection recorded or already present." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/console/e/{environment}/v1/webhook-endpoints": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints for the authenticated workspace", "description": "List webhook endpoints for the authenticated workspace. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Webhooks"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["WHK-001"], "responses": { "200": { "description": "Environment-scoped webhook endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create an HTTPS webhook endpoint and reveal its signing secret once", "description": "Create an HTTPS webhook endpoint and reveal its signing secret once. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Webhooks"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["WHK-001", "AUTH-008", "AUTH-009"], "parameters": [{ "$ref": "#/components/parameters/SecretCommandKey" }, { "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/Conflict" }, "400": { "$ref": "#/components/responses/ValidationProblem" }, "201": { "description": "Endpoint created and signing secret revealed once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealedWebhookSecretResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/console/e/{environment}/v1/webhook-endpoints/{endpoint_id}": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update webhook endpoint routing and status", "description": "Update webhook endpoint routing and status. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Webhooks"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["WHK-001", "AUTH-008", "AUTH-009"], "parameters": [{ "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "200": { "description": "Endpoint updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } }, "delete": { "operationId": "disableWebhookEndpoint", "summary": "Disable a webhook endpoint", "description": "Disable a webhook endpoint. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Webhooks"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["WHK-001", "AUTH-008", "AUTH-009"], "parameters": [{ "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/CsrfToken" }], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Endpoint disabled." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/console/e/{environment}/v1/webhook-endpoints/{endpoint_id}/secret-rotations": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate a webhook signing secret with bounded overlap", "description": "Rotate a webhook signing secret with bounded overlap. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Webhooks"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["WHK-001", "AUTH-008", "AUTH-009"], "parameters": [{ "$ref": "#/components/parameters/SecretCommandKey" }, { "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/CsrfToken" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateWebhookSecretRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/ValidationProblem" }, "201": { "description": "New signing secret revealed once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedWebhookSecretResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/groups": { "get": { "operationId": "listRecipientGroups", "summary": "List environment-scoped recipient groups", "description": "List environment-scoped recipient groups. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["API-001", "GRP-001"], "security": [{ "mandaiApiKey": [] }], "responses": { "200": { "description": "Recipient groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createRecipientGroup", "summary": "Create a transactional recipient group", "description": "Create a transactional recipient group. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["API-001", "GRP-001", "GRP-002"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "$ref": "#/components/parameters/AutomationCommandKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientGroupRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "201": { "description": "Group created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/groups/{group_id}/members": { "post": { "operationId": "addRecipientGroupMembers", "summary": "Add encrypted, deduplicated recipients to a group", "description": "Add encrypted, deduplicated recipients to a group. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["GRP-004", "GRP-005", "GRP-006"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "$ref": "#/components/parameters/AutomationCommandKey" }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^grp_[A-Za-z0-9_-]+$" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddRecipientGroupMembersRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "200": { "description": "Import result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberImportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/groups/{group_id}": { "delete": { "operationId": "archiveRecipientGroup", "summary": "Archive a recipient group without rewriting schedule snapshots", "description": "Archive a recipient group without rewriting schedule snapshots. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["GRP-010"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "$ref": "#/components/parameters/AutomationCommandKey" }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^grp_[A-Za-z0-9_-]+$" } }], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationProblem" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "204": { "description": "Group archived." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/templates": { "get": { "operationId": "listMessageTemplates", "summary": "List message templates with their latest immutable version", "description": "List message templates with their latest immutable version. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["API-001", "TPL-001", "TPL-004"], "security": [{ "mandaiApiKey": [] }], "responses": { "200": { "description": "Message templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTemplateListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createMessageTemplate", "summary": "Create a message template and its first immutable version", "description": "Create a message template and its first immutable version. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["TPL-001", "TPL-002", "TPL-003"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "$ref": "#/components/parameters/AutomationCommandKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageTemplateRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "201": { "description": "Template created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTemplateResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/templates/{template_id}/versions": { "post": { "operationId": "publishMessageTemplateVersion", "summary": "Publish a new immutable template version", "description": "Publish a new immutable template version. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["TPL-004", "TPL-005"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "$ref": "#/components/parameters/AutomationCommandKey" }, { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tpl_[A-Za-z0-9_-]+$" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["body"], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 320 } } } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "201": { "description": "Version published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTemplateResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/schedules": { "get": { "operationId": "listMessageSchedules", "summary": "List message schedules and dispatch counts", "description": "List message schedules and dispatch counts. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["API-001", "SCH-001", "SCH-011"], "security": [{ "mandaiApiKey": [] }], "responses": { "200": { "description": "Schedules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageScheduleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createMessageSchedule", "summary": "Schedule a group snapshot with a pinned template version", "description": "Schedule a group snapshot with a pinned template version. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["SCH-001", "SCH-003", "SCH-004", "SCH-005"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageScheduleRequest" } } } }, "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "201": { "description": "Schedule created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageScheduleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationProblem" } } } }, "/v1/schedules/{schedule_id}": { "delete": { "operationId": "cancelMessageSchedule", "summary": "Cancel a schedule before processing starts", "description": "Cancel a schedule before processing starts. Requires an environment-scoped credential with the corresponding resource capability; Sandbox and Production remain isolated.", "tags": ["Recipient automation"], "x-mandai-requirements": ["SCH-001", "SCH-012"], "security": [{ "mandaiApiKey": [] }], "parameters": [{ "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sch_[A-Za-z0-9_-]+$" } }], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "204": { "description": "Schedule canceled." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/console/e/{environment}/v1/webhook-deliveries": { "servers": [{ "url": "https://mandaionline.com", "description": "Canonical console BFF" }], "parameters": [{ "$ref": "#/components/parameters/ConsoleEnvironment" }], "get": { "operationId": "listWebhookDeliveries", "summary": "Inspect recent webhook delivery receipts", "description": "Inspect recent webhook delivery receipts. Uses the authenticated browser session and the current workspace permissions; it is not an API-key endpoint.", "tags": ["Webhooks"], "security": [{ "mandaiSession": [] }], "x-mandai-requirements": ["WHK-001"], "responses": { "200": { "description": "Up to 100 recent delivery receipts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "mandaiSession": { "type": "apiKey", "in": "cookie", "name": "__Host-mandai_session", "description": "Opaque, revocable, expiring Mandai browser session. Google tokens are never accepted as a session." }, "mandaiApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Mandai API key", "description": "Environment-scoped Mandai API key. Google tokens are never accepted." } }, "responses": { "RateLimited": { "description": "Ingress quota exceeded. Wait for Retry-After and preserve the original idempotency key.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds to wait before retrying.", "example": 60 }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Structured Field quota policy per draft-ietf-httpapi-ratelimit-headers-11.", "example": "\"message\";q=120;w=60" }, "RateLimit": { "schema": { "type": "string" }, "description": "Exhausted quota and conservative retry window; no counter is advertised on allowed calls.", "example": "\"message\";r=0;t=60" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "The credential is missing, invalid, revoked, or belongs to another environment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "IdempotencyConflict": { "description": "The idempotency key was already used with different semantic content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "The requested environment or key lifecycle transition conflicts with current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "The API key was not found in the authenticated tenant and environment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ValidationProblem": { "description": "The request failed validation before persistence.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InvalidAuthentication": { "description": "The OAuth callback is missing, expired, replayed, or not bound to the initiating browser.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "IdentityConflict": { "description": "The verified email already belongs to a different issuer-and-subject identity and is not linked automatically.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "The authenticated session lacks required CSRF, origin, role, or capability evidence.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "AuthenticationUnavailable": { "description": "Google authentication is not configured or a required identity dependency is unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": { "ConsoleEnvironment": { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } }, "ApiKeyId": { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^key_[A-Za-z0-9_-]+$" } }, "WebhookEndpointId": { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$" } }, "CsrfToken": { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 32 }, "description": "Must match the CSRF cookie and server-side one-way value; Origin must also be allowed." }, "AutomationCommandKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended for group create/import/archive and template create/publish. Retain a random key per intent. Equivalent normalized payload and actor replay the original result, including counts and revision, not the current resource. Scope: tenant/environment/action. Changed payload or actor returns 409 idempotency_conflict. Invalid supplied key returns 422; omission preserves non-idempotent behavior. New key means new intent.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9:_-]{8,128}$" } }, "SecretCommandKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended for credential create/rotate. Retain one high-entropy key per intent and reuse it after transport failure. Scope is tenant/environment/action. Same normalized payload and actor return 409 secret_already_revealed with resource_id; changed payload or actor returns 409 idempotency_conflict. No secret is replayed. A new key is a new intent. Omission preserves non-idempotent legacy behavior; invalid supplied keys return 400 invalid_idempotency_key.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9:_-]{8,128}$" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Equivalent schedule creation replays the original resource; reuse with different semantic content returns a conflict.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "schemas": { "Environment": { "type": "string", "enum": ["production", "sandbox"] }, "ResponseMeta": { "type": "object", "additionalProperties": false, "required": ["request_id", "environment"], "properties": { "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$" }, "environment": { "$ref": "#/components/schemas/Environment" } } }, "HealthResponse": { "type": "object", "additionalProperties": false, "required": ["status"], "properties": { "status": { "type": "string", "const": "ok" } } }, "ReadinessResponse": { "type": "object", "additionalProperties": false, "required": ["status"], "properties": { "status": { "type": "string", "const": "ready" } } }, "UnavailableResponse": { "type": "object", "additionalProperties": false, "required": ["status"], "properties": { "status": { "type": "string", "const": "unavailable" } } }, "MembershipRole": { "type": "string", "enum": ["owner", "administrator", "member", "read_only"] }, "ConsoleCapability": { "type": "string", "enum": ["api_keys:read", "api_keys:write", "messages:read", "messages:create", "groups:read", "groups:write", "templates:read", "templates:write", "schedules:read", "schedules:write", "webhooks:read", "webhooks:write", "members:read", "members:write", "workspace:read", "workspace:write"] }, "AssignableMembershipRole": { "type": "string", "enum": ["administrator", "member", "read_only"] }, "SwitchWorkspaceRequest": { "type": "object", "additionalProperties": false, "required": ["tenant_id"], "properties": { "tenant_id": { "type": "string", "pattern": "^ten_[A-Za-z0-9_-]+$" } } }, "InviteMemberRequest": { "type": "object", "additionalProperties": false, "required": ["email", "role"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "role": { "$ref": "#/components/schemas/AssignableMembershipRole" } } }, "UpdateMemberRoleRequest": { "type": "object", "additionalProperties": false, "required": ["role"], "properties": { "role": { "$ref": "#/components/schemas/AssignableMembershipRole" } } }, "MemberListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "object", "required": ["members", "invitations"], "properties": { "members": { "type": "array", "items": { "type": "object" } }, "invitations": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "Tenant": { "type": "object", "additionalProperties": false, "required": ["id", "slug", "name", "account_status", "subscription_status"], "properties": { "id": { "type": "string", "pattern": "^ten_[A-Za-z0-9_-]+$" }, "slug": { "type": "string" }, "name": { "type": "string" }, "account_status": { "type": "string", "enum": ["sandbox", "active", "suspended", "closed"] }, "subscription_status": { "type": "string", "enum": ["none", "trialing", "active", "past_due", "canceled"] } } }, "OnboardingFirstFlow": { "type": "string", "enum": ["otp", "order-status", "alerts", "other"] }, "OnboardingStartMode": { "type": "string", "enum": ["sandbox", "api", "migration"] }, "CompleteOnboardingRequest": { "type": "object", "additionalProperties": false, "required": ["display_name", "first_flow", "start_mode"], "properties": { "display_name": { "type": "string", "minLength": 2, "maxLength": 80 }, "first_flow": { "$ref": "#/components/schemas/OnboardingFirstFlow" }, "start_mode": { "$ref": "#/components/schemas/OnboardingStartMode" } } }, "CompleteOnboardingResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "object", "additionalProperties": false, "required": ["display_name", "first_flow", "start_mode", "completed_at", "next_route"], "properties": { "display_name": { "type": "string" }, "first_flow": { "$ref": "#/components/schemas/OnboardingFirstFlow" }, "start_mode": { "$ref": "#/components/schemas/OnboardingStartMode" }, "completed_at": { "type": "string", "format": "date-time" }, "next_route": { "type": "string", "pattern": "^/" } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "UserExperience": { "type": "object", "additionalProperties": false, "required": ["locale", "timezone", "preferred_code_language", "last_environment", "version"], "properties": { "locale": { "type": ["string", "null"] }, "timezone": { "type": ["string", "null"] }, "preferred_code_language": { "type": ["string", "null"], "enum": ["typescript", "javascript", "curl", null] }, "last_environment": { "oneOf": [{ "$ref": "#/components/schemas/Environment" }, { "type": "null" }] }, "version": { "type": "integer", "minimum": 1 } } }, "MembershipExperience": { "type": "object", "additionalProperties": false, "required": ["first_flow", "start_mode", "onboarding_status", "onboarding_version", "completed_at", "preferred_code_language", "version"], "properties": { "first_flow": { "oneOf": [{ "$ref": "#/components/schemas/OnboardingFirstFlow" }, { "type": "null" }] }, "start_mode": { "oneOf": [{ "$ref": "#/components/schemas/OnboardingStartMode" }, { "type": "null" }] }, "onboarding_status": { "type": "string", "enum": ["not_started", "in_progress", "completed", "skipped"] }, "onboarding_version": { "type": "integer", "minimum": 1 }, "completed_at": { "type": ["string", "null"], "format": "date-time" }, "preferred_code_language": { "type": ["string", "null"], "enum": ["typescript", "javascript", "curl", null] }, "version": { "type": "integer", "minimum": 1 } } }, "SessionMembership": { "type": "object", "additionalProperties": false, "required": ["id", "role", "authz_version", "capabilities"], "properties": { "id": { "type": "string", "pattern": "^mem_[A-Za-z0-9_-]+$" }, "role": { "$ref": "#/components/schemas/MembershipRole" }, "authz_version": { "type": "integer", "minimum": 1 }, "capabilities": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConsoleCapability" } } } }, "User": { "type": "object", "additionalProperties": false, "required": ["id", "display_name", "email", "experience"], "properties": { "id": { "type": "string", "pattern": "^usr_[A-Za-z0-9_-]+$" }, "display_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "experience": { "$ref": "#/components/schemas/UserExperience" } } }, "SessionResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "object", "additionalProperties": false, "required": ["session", "user", "tenant", "role", "membership", "experience", "memberships", "csrf_token"], "properties": { "session": { "type": "object", "additionalProperties": false, "required": ["expires_at"], "properties": { "expires_at": { "type": "string", "format": "date-time" } } }, "tenant": { "$ref": "#/components/schemas/Tenant" }, "user": { "$ref": "#/components/schemas/User" }, "role": { "$ref": "#/components/schemas/MembershipRole" }, "membership": { "$ref": "#/components/schemas/SessionMembership" }, "experience": { "$ref": "#/components/schemas/MembershipExperience" }, "memberships": { "type": "array", "items": { "type": "object" } }, "csrf_token": { "type": "string", "minLength": 32 } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ApiKeyCapability": { "type": "string", "enum": ["messages:preview", "messages:send", "messages:read", "webhooks:read", "usage:read", "groups:read", "groups:write", "templates:read", "templates:write", "schedules:read", "schedules:write"] }, "ApiKeyMetadata": { "type": "object", "additionalProperties": false, "required": ["id", "name", "environment", "key_prefix", "capabilities", "replaces_key_id", "created_at", "expires_at", "last_used_at", "revoked_at", "status"], "properties": { "id": { "type": "string", "pattern": "^key_[A-Za-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "environment": { "$ref": "#/components/schemas/Environment" }, "key_prefix": { "type": "string", "pattern": "^mandai_(sbx|prd)_[A-Za-z0-9_-]{12}$" }, "capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ApiKeyCapability" } }, "replaces_key_id": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": ["string", "null"], "format": "date-time" }, "last_used_at": { "type": ["string", "null"], "format": "date-time" }, "revoked_at": { "type": ["string", "null"], "format": "date-time" }, "status": { "type": "string", "enum": ["active", "expired", "revoked"] } } }, "CreateApiKeyRequest": { "type": "object", "additionalProperties": false, "required": ["name", "environment", "capabilities"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "environment": { "$ref": "#/components/schemas/Environment" }, "capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ApiKeyCapability" } }, "expires_at": { "type": ["string", "null"], "format": "date-time" } } }, "RotateApiKeyRequest": { "type": "object", "additionalProperties": false, "required": ["overlap_seconds"], "properties": { "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } } }, "ApiKeyListResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyMetadata" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "RevealedApiKeyResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "object", "additionalProperties": false, "required": ["key", "api_key", "reveal_once"], "properties": { "key": { "$ref": "#/components/schemas/ApiKeyMetadata" }, "api_key": { "type": "string", "writeOnly": true, "pattern": "^mandai_(sbx|prd)_[A-Za-z0-9_-]{12}\\.[A-Za-z0-9_-]{43}$" }, "reveal_once": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MessageInput": { "type": "object", "additionalProperties": false, "required": ["to", "body"], "properties": { "to": { "type": "string", "pattern": "^\\+55[1-9][0-9]{9,10}$", "description": "Brazilian E.164 destination." }, "body": { "type": "string", "minLength": 1, "maxLength": 1600 }, "message_type": { "type": "string", "enum": ["transactional", "authentication"] }, "metadata": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "string", "maxLength": 256 }, "maxProperties": 10 } } }, "MessagePreviewRequest": { "allOf": [{ "$ref": "#/components/schemas/MessageInput" }] }, "CreateMessageRequest": { "allOf": [{ "$ref": "#/components/schemas/MessageInput" }] }, "MessagePreview": { "type": "object", "additionalProperties": false, "required": ["normalized_to", "encoding", "character_count", "segment_count", "estimated_maximum_charge"], "properties": { "normalized_to": { "type": "string", "pattern": "^\\+55[1-9][0-9]{9,10}$" }, "encoding": { "type": "string", "enum": ["gsm-7", "ucs-2"] }, "character_count": { "type": "integer", "minimum": 1, "description": "Unicode code-point count. Segment calculation separately accounts for two-septet GSM extension characters and two-code-unit non-BMP UCS-2 characters." }, "segment_count": { "type": "integer", "minimum": 1, "description": "Uses 160/153 septets for GSM-7 and 70/67 code units for UCS-2, without splitting escape sequences or surrogate pairs." }, "estimated_maximum_charge": { "type": "object", "additionalProperties": false, "required": ["currency", "amount", "pricing_version"], "properties": { "currency": { "type": "string", "const": "BRL" }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "pricing_version": { "type": "string", "description": "Immutable pricing-policy identifier used for this estimate." } } } } }, "MessagePreviewResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/MessagePreview" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "CreatedMessage": { "type": "object", "additionalProperties": false, "required": ["message_id", "workspace_id", "environment", "status", "encoding", "estimated_segments", "estimated_maximum_charge", "created_at"], "properties": { "message_id": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" }, "workspace_id": { "type": "string", "pattern": "^ten_[A-Za-z0-9_-]+$", "description": "Workspace that owns this message intent. Use the same workspace in the console to inspect it." }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "type": "string", "const": "queued" }, "encoding": { "type": "string", "enum": ["gsm-7", "ucs-2"] }, "estimated_segments": { "type": "integer", "minimum": 1 }, "estimated_maximum_charge": { "type": "object", "additionalProperties": false, "required": ["currency", "amount", "pricing_version"], "properties": { "currency": { "type": "string", "const": "BRL" }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "pricing_version": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateMessageResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/CreatedMessage" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MessageStatus": { "type": "string", "enum": ["queued", "dispatching", "provider_acknowledged", "delivered", "failed", "unknown"] }, "MessageEvidenceEvent": { "type": "object", "additionalProperties": false, "required": ["id", "sequence", "type", "status", "reason_code", "occurred_at", "recorded_at", "synthetic"], "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]+$" }, "sequence": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "oneOf": [{ "$ref": "#/components/schemas/MessageStatus" }, { "type": "null" }] }, "reason_code": { "type": ["string", "null"], "maxLength": 128 }, "occurred_at": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time" }, "synthetic": { "type": "boolean" } } }, "MaximumCharge": { "type": "object", "additionalProperties": false, "required": ["currency", "amount", "pricing_version"], "properties": { "currency": { "type": "string", "const": "BRL" }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "pricing_version": { "type": "string", "minLength": 1 } } }, "MessageEvidence": { "type": "object", "additionalProperties": false, "required": ["message_id", "environment", "status", "message_type", "encoding", "estimated_segments", "estimated_maximum_charge", "created_at", "updated_at", "route", "latency", "events"], "properties": { "message_id": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "message_type": { "type": "string", "enum": ["transactional", "authentication"] }, "encoding": { "type": "string", "enum": ["gsm-7", "ucs-2"] }, "estimated_segments": { "type": "integer", "minimum": 1 }, "estimated_maximum_charge": { "$ref": "#/components/schemas/MaximumCharge" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "route": { "oneOf": [ { "$ref": "#/components/schemas/MessageRouteEvidence" }, { "type": "null" } ] }, "latency": { "$ref": "#/components/schemas/MessageLatencyEvidence" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEvidenceEvent" } } } }, "MessageRouteEvidence": { "type": "object", "additionalProperties": false, "required": ["id", "provider", "provider_status", "carrier", "carrier_source"], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "minLength": 1, "maxLength": 64 }, "provider_status": { "type": ["string", "null"], "maxLength": 64 }, "carrier": { "type": ["string", "null"], "maxLength": 64 }, "carrier_source": { "type": ["string", "null"], "enum": ["provider", null] } } }, "MessageLatencyEvidence": { "type": "object", "additionalProperties": false, "required": ["provider_acknowledgement_ms", "delivery_observation_ms"], "properties": { "provider_acknowledgement_ms": { "type": ["integer", "null"], "minimum": 0 }, "delivery_observation_ms": { "type": ["integer", "null"], "minimum": 0 } } }, "MessageSummary": { "type": "object", "additionalProperties": false, "required": ["message_id", "environment", "status", "message_type", "encoding", "estimated_segments", "estimated_maximum_charge", "created_at", "updated_at"], "properties": { "message_id": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "message_type": { "type": "string", "enum": ["transactional", "authentication"] }, "encoding": { "type": "string", "enum": ["gsm-7", "ucs-2"] }, "estimated_segments": { "type": "integer", "minimum": 1 }, "estimated_maximum_charge": { "$ref": "#/components/schemas/MaximumCharge" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MessageSummaryListResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MessageSummary" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MessageEvidenceResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/MessageEvidence" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ReliabilityResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/ReliabilityEvidence" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ReliabilityEvidence": { "type": "object", "additionalProperties": false, "required": ["environment", "period", "window_started_at", "window_ended_at", "observed_at", "sample", "delivery", "latency", "throughput", "stability", "routes", "service_level", "freshness_at"], "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "period": { "type": "string", "enum": ["24h", "7d", "30d"] }, "window_started_at": { "type": "string", "format": "date-time" }, "window_ended_at": { "type": "string", "format": "date-time" }, "observed_at": { "type": "string", "format": "date-time" }, "sample": { "type": "object", "additionalProperties": false, "required": ["attempts", "capped"], "properties": { "attempts": { "type": "integer", "minimum": 0 }, "capped": { "type": "boolean" } } }, "delivery": { "$ref": "#/components/schemas/ReliabilityDelivery" }, "latency": { "$ref": "#/components/schemas/ReliabilityLatency" }, "throughput": { "$ref": "#/components/schemas/ReliabilityThroughput" }, "stability": { "$ref": "#/components/schemas/ReliabilityStability" }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/ReliabilityRoute" } }, "service_level": { "$ref": "#/components/schemas/ReliabilityServiceLevel" }, "freshness_at": { "type": ["string", "null"], "format": "date-time" } } }, "ReliabilityDelivery": { "type": "object", "additionalProperties": false, "required": ["delivered", "failed", "awaiting_receipt", "receipt_unavailable", "submitted_without_acknowledgement", "terminal_rate", "by_carrier"], "properties": { "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "awaiting_receipt": { "type": "integer", "minimum": 0 }, "receipt_unavailable": { "type": "integer", "minimum": 0 }, "submitted_without_acknowledgement": { "type": "integer", "minimum": 0 }, "terminal_rate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "by_carrier": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["carrier", "delivered", "failed", "awaiting_receipt", "receipt_unavailable", "terminal_rate"], "properties": { "carrier": { "type": ["string", "null"], "maxLength": 64 }, "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "awaiting_receipt": { "type": "integer", "minimum": 0 }, "receipt_unavailable": { "type": "integer", "minimum": 0 }, "terminal_rate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 } } } } } }, "ReliabilityLatency": { "type": "object", "additionalProperties": false, "required": ["acknowledgement_p95_ms", "acknowledgement_p99_ms", "delivery_p95_ms", "delivery_p99_ms"], "properties": { "acknowledgement_p95_ms": { "type": ["integer", "null"], "minimum": 0 }, "acknowledgement_p99_ms": { "type": ["integer", "null"], "minimum": 0 }, "delivery_p95_ms": { "type": ["integer", "null"], "minimum": 0 }, "delivery_p99_ms": { "type": ["integer", "null"], "minimum": 0 } } }, "ReliabilityThroughput": { "type": "object", "additionalProperties": false, "required": ["messages_per_minute", "segments_per_minute", "peak_messages_per_minute"], "properties": { "messages_per_minute": { "type": "number", "minimum": 0 }, "segments_per_minute": { "type": "number", "minimum": 0 }, "peak_messages_per_minute": { "type": "integer", "minimum": 0 } } }, "ReliabilityStability": { "type": "object", "additionalProperties": false, "required": ["provider_acceptance_rate", "terminal_evidence_rate"], "properties": { "provider_acceptance_rate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "terminal_evidence_rate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 } } }, "ReliabilityRoute": { "type": "object", "additionalProperties": false, "required": ["id", "provider", "attempts", "provider_acceptance_rate"], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "minLength": 1, "maxLength": 64 }, "attempts": { "type": "integer", "minimum": 0 }, "provider_acceptance_rate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 } } }, "ReliabilityServiceLevel": { "type": "object", "additionalProperties": false, "required": ["kind", "target", "evaluated", "label"], "properties": { "kind": { "type": "string", "enum": ["contractual_sla", "operational_slo"] }, "target": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "evaluated": { "type": "boolean" }, "label": { "type": "string", "minLength": 1, "maxLength": 240 } } }, "WebhookEventType": { "type": "string", "enum": ["message.queued", "message.provider_acknowledged", "message.delivered", "message.failed", "message.unknown"] }, "WebhookEndpoint": { "type": "object", "additionalProperties": false, "required": ["id", "environment", "name", "url", "subscriptions", "secret_version", "status", "created_at", "updated_at"], "properties": { "id": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$" }, "environment": { "$ref": "#/components/schemas/Environment" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "subscriptions": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "secret_version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": ["active", "disabled"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateWebhookEndpointRequest": { "type": "object", "additionalProperties": false, "required": ["name", "url", "subscriptions"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "subscriptions": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } } } }, "UpdateWebhookEndpointRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "subscriptions": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "status": { "type": "string", "enum": ["active", "disabled"] } } }, "RotateWebhookSecretRequest": { "type": "object", "additionalProperties": false, "required": ["overlap_seconds"], "properties": { "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } } }, "WebhookEndpointListResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "WebhookEndpointResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "RevealedWebhookSecretResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "object", "additionalProperties": false, "required": ["endpoint", "secret", "reveal_once"], "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "writeOnly": true, "pattern": "^whsec_[A-Za-z0-9_-]{43}$" }, "reveal_once": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "RotatedWebhookSecretResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "object", "additionalProperties": false, "required": ["endpoint_id", "secret", "secret_version", "reveal_once"], "properties": { "endpoint_id": { "type": "string" }, "secret": { "type": "string", "writeOnly": true, "pattern": "^whsec_[A-Za-z0-9_-]{43}$" }, "secret_version": { "type": "integer", "minimum": 2 }, "reveal_once": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "required": ["id", "endpoint_id", "endpoint_name", "event_id", "event_type", "status", "attempt_count", "last_response_status", "last_latency_ms", "created_at", "completed_at"], "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "endpoint_name": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "$ref": "#/components/schemas/WebhookEventType" }, "status": { "type": "string", "enum": ["pending", "delivering", "succeeded", "exhausted"] }, "attempt_count": { "type": "integer", "minimum": 0 }, "last_response_status": { "type": ["integer", "null"] }, "last_latency_ms": { "type": ["integer", "null"], "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": ["string", "null"], "format": "date-time" } } }, "WebhookDeliveryListResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "RecipientGroup": { "type": "object", "additionalProperties": false, "required": ["group_id", "name", "purpose", "status", "revision", "member_count", "created_at", "updated_at"], "properties": { "group_id": { "type": "string", "pattern": "^grp_[A-Za-z0-9_-]+$" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "status": { "type": "string", "enum": ["active", "archived"] }, "revision": { "type": "integer", "minimum": 1 }, "member_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateRecipientGroupRequest": { "type": "object", "additionalProperties": false, "required": ["name", "purpose"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 240 } } }, "AddRecipientGroupMembersRequest": { "type": "object", "additionalProperties": false, "required": ["members"], "properties": { "members": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "additionalProperties": false, "required": ["to"], "properties": { "to": { "type": "string", "minLength": 10, "maxLength": 20 }, "variables": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 120 } } } } } } }, "RecipientGroupResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/RecipientGroup" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "RecipientGroupListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientGroup" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "GroupMemberImportResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "object", "required": ["added", "duplicates", "revision"], "properties": { "added": { "type": "integer", "minimum": 0 }, "duplicates": { "type": "integer", "minimum": 0 }, "revision": { "type": "integer", "minimum": 1 } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MessageTemplate": { "type": "object", "additionalProperties": false, "required": ["template_id", "name", "status", "latest_version", "version_id", "body", "variables", "created_at", "updated_at"], "properties": { "template_id": { "type": "string", "pattern": "^tpl_[A-Za-z0-9_-]+$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["active", "archived"] }, "latest_version": { "type": "integer", "minimum": 1 }, "version_id": { "type": "string" }, "body": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateMessageTemplateRequest": { "type": "object", "additionalProperties": false, "required": ["name", "body"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "body": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "MessageTemplateResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/MessageTemplate" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MessageTemplateListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageTemplate" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "CreateMessageScheduleRequest": { "type": "object", "additionalProperties": false, "required": ["name", "group_id", "template_id", "scheduled_for"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "group_id": { "type": "string", "pattern": "^grp_[A-Za-z0-9_-]+$" }, "template_id": { "type": "string", "pattern": "^tpl_[A-Za-z0-9_-]+$" }, "scheduled_for": { "type": "string", "format": "date-time" } } }, "MessageSchedule": { "type": "object", "additionalProperties": false, "required": ["schedule_id", "name", "status", "group", "template", "scheduled_for", "recipient_count", "dispatched_count", "failed_count", "created_at", "updated_at", "completed_at", "canceled_at"], "properties": { "schedule_id": { "type": "string", "pattern": "^sch_[A-Za-z0-9_-]+$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["scheduled", "processing", "completed", "completed_with_failures", "canceled"] }, "group": { "type": "object", "required": ["group_id", "name", "revision"], "properties": { "group_id": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 } } }, "template": { "type": "object", "required": ["template_id", "name", "version_id"], "properties": { "template_id": { "type": "string" }, "name": { "type": "string" }, "version_id": { "type": "string" } } }, "scheduled_for": { "type": "string", "format": "date-time" }, "recipient_count": { "type": "integer", "minimum": 1 }, "dispatched_count": { "type": "integer", "minimum": 0 }, "failed_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": ["string", "null"], "format": "date-time" }, "canceled_at": { "type": ["string", "null"], "format": "date-time" } } }, "MessageScheduleResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/MessageSchedule" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MessageScheduleListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSchedule" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ProblemField": { "type": "object", "additionalProperties": false, "required": ["path", "code"], "properties": { "path": { "type": "string" }, "code": { "type": "string" } } }, "Problem": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "code", "detail", "request_id", "environment"], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string" }, "resource_id": { "type": "string", "description": "Only for secret_already_revealed: the committed credential resource, never the secret." }, "detail": { "type": "string" }, "resolution": { "type": "string", "description": "Safe next steps for resolving this error." }, "documentation_url": { "type": "string", "format": "uri" }, "request_id": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemField" } } } } } } }