{ "openapi": "3.0.3", "info": { "title": "HailMe Platform API", "version": "0.4.0", "description": "Implemented standalone backend API and internal cabinet contracts. Service keys are project/environment scoped and backend-only: requests with a browser Origin header are rejected. TEST uses FAKE delivery; LIVE routes require separate operator admission. Verify is TEST/FAKE only. Published JVM SDK dev.3 has notification/installation/template/usage methods; Verify currently uses HTTP. Cabinet sessions and application users are separate identities. Pricing samples, preparation-only channels and sandbox invoices are not a LIVE commercial offer." }, "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "tags": [ { "name": "Data API" }, { "name": "Account" }, { "name": "Account Webhooks" }, { "name": "Provider Callback" }, { "name": "Verify TEST", "description": "Synthetic SMS/email OTP, billing and affiliation. Not mobile phone login or LIVE delivery." }, { "name": "First-party HailMe", "description": "Restricted compatibility protocol for the HailMe mobile backend; not external client onboarding." }, { "name": "Account Auth", "description": "Cabinet internal email sign-in, separate from commercial Verify and mobile auth." }, { "name": "Telegram TEST", "description": "Isolated synthetic opt-in and fake delivery. No real bot or LIVE connection." } ], "paths": { "/v1/notifications": { "post": { "operationId": "createNotification", "summary": "Durably enqueue one SMS, PUSH or isolated TEST/FAKE TELEGRAM command", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "202": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 16 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "application/json is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotification" } } } }, "description": "notifications:write. SMS phone or PUSH installationId discriminator, approved channel template. Application/environment scoped idempotency survives service-key rotation; provider credentials not accepted in body. Local A01/A05 implementation is opt-in, TEST FAKE only for new notifications; see api-handoff.md. No deployment or real provider readiness implied.", "x-implementation-status": "local-test-only" } }, "/v1/notifications/{notificationId}": { "get": { "operationId": "getNotification", "summary": "Read own notification state", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/NotificationId" } ], "description": "notifications:read. Foreign application/environment ID returns 404. ACCEPTED is not receipt; UNKNOWN must not be blindly resent. Local A01/A05 implementation is opt-in, TEST FAKE only for new notifications; see api-handoff.md. No deployment or real provider readiness implied.", "x-implementation-status": "local-test-only" } }, "/v1/templates": { "get": { "operationId": "listTemplates", "summary": "List application-approved templates", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "templates:read. Scoped immutable approved template IDs, exact locales, channels, variable names, parameterSchema and payloadKeys. TEST template creation is available to owners in the cabinet. Published changes require a new versioned ID. Existing SDK string parameters remain compatible.", "x-implementation-status": "local-test-only" } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Read application/environment usage and cap", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" } ], "description": "Backend-only usage:read. Current service key/scopes/revocation rechecked. Retained operation/attempt counts, lifetime per-channel admission caps, explicit FAKE count. SMS segments and billing totals unavailable.", "x-implementation-status": "local-durable-usage-and-quotas" } }, "/account/auth/email/challenges": { "post": { "operationId": "requestAccountChallenge", "summary": "Begin HailMe Platform browser login", "tags": [ "Account Auth" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [], "responses": { "202": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChallenge" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 2 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "application/json is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChallengeRequest" } } } }, "description": "Neutral response and rate/cooldown; no staff role requirement or consumer trial creation. W01 implemented locally with isolated account cookie/proof purpose, dedicated protection keys and exact HTTPS Origin/Host policy. Real OTP sender remains disabled; local allowlisted inbox is internal only. See account-handoff.md.", "x-implementation-status": "local-test-auth" } }, "/account/auth/email/verify": { "post": { "operationId": "verifyAccountChallenge", "summary": "Verify identity and create account cookie session", "tags": [ "Account Auth" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } }, "headers": { "Set-Cookie": { "description": "hailme_platform_session; HttpOnly; Secure; Path=/account; host-only; SameSite=Strict", "schema": { "type": "string" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 2 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "application/json is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerifyRequest" } } } }, "description": "Issue purpose-scoped session cookie only; no access/refresh token returned for browser storage. W01 implemented locally with isolated account cookie/proof purpose, dedicated protection keys and exact HTTPS Origin/Host policy. Real OTP sender remains disabled; local allowlisted inbox is internal only. See account-handoff.md.", "x-implementation-status": "local-test-auth" } }, "/account/api/session": { "get": { "operationId": "getAccountSession", "summary": "Read own identity and organization memberships", "tags": [ "Account Auth" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-implementation-status": "local-test-auth", "description": " W01 implemented locally with isolated account cookie/proof purpose, dedicated protection keys and exact HTTPS Origin/Host policy. Real OTP sender remains disabled; local allowlisted inbox is internal only. See account-handoff.md." } }, "/account/auth/logout": { "post": { "operationId": "logoutAccount", "summary": "Revoke this account session", "tags": [ "Account Auth" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "204": { "description": "Successful operation" }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "description": "Idempotent logout; queued notifications and other account purposes are not cancelled. W01 implemented locally with isolated account cookie/proof purpose, dedicated protection keys and exact HTTPS Origin/Host policy. Real OTP sender remains disabled; local allowlisted inbox is internal only. See account-handoff.md.", "x-implementation-status": "local-test-auth" } }, "/account/api/organizations/{organizationId}/applications": { "get": { "operationId": "listApplications", "summary": "List applications in own organization", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "x-implementation-status": "local-test-workspace" }, "post": { "operationId": "createApplication", "summary": "Create application with TEST enabled and LIVE disabled", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "201": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationInput" } } } }, "description": "OWNER only. Atomic application plus TEST enabled/LIVE disabled and permanent organization-scoped idempotency receipt. Name is trimmed; same key and normalized name replay the original 201 DTO even if environment enabled flags later change. Changed name returns 409. Session, current OWNER membership and CSRF are checked on every replay. Up to 30 new applications per identity per fixed hour; successful replays do not consume this limit. No dispatch or environment enablement.", "x-implementation-status": "local-test-workspace" } }, "/account/api/applications/{applicationId}/environments/{environment}": { "get": { "operationId": "getEnvironmentConfiguration", "summary": "Read own environment readiness and safe metadata", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentConfiguration" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" } ], "x-implementation-status": "local-test-workspace" } }, "/account/api/applications/{applicationId}/environments/{environment}/keys": { "get": { "operationId": "listServiceKeys", "summary": "List key metadata without secrets", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" } ], "x-implementation-status": "local-test-keys", "description": "OWNER only. Current account session and membership are required; TEST/LIVE scoped metadata including revoked keys, without secret or digest. Works when environment is disabled. Requires explicit Platform API opt-in; account-only mode returns 503." }, "post": { "operationId": "createServiceKey", "summary": "Create service key with one-time secret reveal", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "201": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyCreated" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyInput" } } } }, "description": "OWNER only, exact Origin and session CSRF. Environment must be enabled (including LIVE); disabled environment returns 409. Up to 20 active keys per application/environment and 30 browser issuance attempts per identity per fixed hour. Same protected storage and credential format as A01. Secret is returned once in this 201 only, stored as HMAC, never recovered by GET. No idempotent secret replay and no automatic retry after a lost response: list metadata, explicitly revoke unread key, then explicitly create a new key. Does not enable environment or real delivery. Requires Platform API opt-in.", "x-implementation-status": "local-test-keys" } }, "/account/api/applications/{applicationId}/environments/{environment}/keys/{keyId}": { "delete": { "operationId": "revokeServiceKey", "summary": "Revoke service key in own environment", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "204": { "description": "Successful operation" }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/KeyId" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "description": "OWNER only, exact Origin and session CSRF. Idempotent 204 for an already revoked own key, foreign app/environment/key returns 404. Listing/revocation remain possible when environment is disabled. Immediately denies new use of the credential, including credentials authenticated before revocation at the next API authorization check. Does not delete accepted jobs.", "x-implementation-status": "local-test-keys" } }, "/account/api/applications/{applicationId}/environments/{environment}/notifications": { "get": { "operationId": "listAccountNotifications", "summary": "Read masked notification journal", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountNotificationPage" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "channel", "in": "query", "description": "Optional channel filter; ALL preserves all channels. Bound to the cursor.", "schema": { "type": "string", "enum": [ "ALL", "SMS", "PUSH" ], "default": "ALL" } }, { "name": "source", "in": "query", "description": "Optional submission source filter; API, cabinet and Geo TEST share the journal. Bound to the cursor.", "schema": { "type": "string", "enum": [ "ALL", "API", "CABINET", "GEO_TEST" ], "default": "ALL" } }, { "name": "from", "in": "query", "description": "Inclusive UTC notification creation time. Supply with to, max 31 days. Omit both for all retained history. Keep unchanged across cursor pages.", "schema": { "type": "string", "format": "date-time", "maxLength": 40 } }, { "name": "to", "in": "query", "description": "Exclusive UTC notification creation time, no later than now. Keep unchanged across cursor pages.", "schema": { "type": "string", "format": "date-time", "maxLength": 40 } } ], "x-implementation-status": "local-account-journal", "description": "Read-only masked account journal. Filters are applied before stable keyset pagination and bound into its signed cursor. New selections must omit cursor. Period refers to notification creation, not attempts. Defaults preserve all retained history. Does not submit notifications or mutate billing. Public service-key notification endpoints are unchanged. Period is UTC [from,to); specify both bounds. CSV in the cabinet applies the accepted period/channel/source selection. Verify costs are separate." } }, "/account/api/applications/{applicationId}/environments/{environment}/notifications/{notificationId}": { "get": { "operationId": "getAccountNotification", "summary": "Read own notification detail", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountNotificationDetail" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/NotificationId" } ], "x-implementation-status": "local-account-journal", "description": "OWNER/DEVELOPER current account session and membership checked in same transaction. Scoped read-only API; API opt-in required, otherwise 503. No real delivery enabled." } }, "/account/api/applications/{applicationId}/environments/{environment}/usage": { "get": { "operationId": "getAccountUsage", "summary": "Read environment usage in portal", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsage" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALL", "SMS", "PUSH" ], "default": "ALL" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALL", "API", "CABINET", "GEO_TEST" ], "default": "ALL" } } ], "x-implementation-status": "test-sandbox-project-costs", "description": "OWNER/DEVELOPER current account session and membership checked in same transaction. Scoped read-only API; API opt-in required, otherwise 503. No real delivery enabled. Only an organization OWNER can read TEST/FAKE project cost snapshots in an explicitly enabled sandbox. LIVE/disabled/restricted costs are unavailable, never fabricated zero amounts. No financial writes occur on usage reads. Period is UTC [from,to); specify both bounds. CSV in the cabinet applies the accepted period/channel/source selection. Verify costs are separate." } }, "/account/api/applications/{applicationId}/environments/{environment}/templates": { "get": { "operationId": "listAccountTemplates", "summary": "Read approved template definitions for portal", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" } ], "x-implementation-status": "planned" } }, "/account/api/applications/{applicationId}/environments/{environment}/webhook": { "put": { "operationId": "configureWebhook", "summary": "Save pending webhook destination", "tags": [ "Account Webhooks" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfiguration" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "description": "W04 control plane only. Account session, current membership and exact Origin/CSRF on mutations. OWNER configures/rotates/verifies; OWNER/DEVELOPER read diagnostics and queue verified TEST events. URL must be HTTPS DNS hostname:443 without userinfo/query/fragment; no network/DNS request is performed. Network sender is absent; host mode DISABLED cannot verify or send, LOCAL_TEST proof is never accepted as a real endpoint verification. A03 notification status outbox and production DNS/IP pinning/HTTP transport remain planned. expectedVersion=0 creates, current version updates; same normalized URL/version can replay a lost PUT. New URL invalidates pending old events and requires a fresh challenge.", "x-implementation-status": "local-notification-webhooks-disabled-host" } }, "/account/api/applications/{applicationId}/environments/{environment}/webhook/signing-key": { "post": { "operationId": "rotateWebhookSigningKey", "summary": "Rotate signing key and enqueue verification challenge", "tags": [ "Account Webhooks" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "201": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningKeyCreated" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "description": "W04 control plane only. Account session, current membership and exact Origin/CSRF on mutations. OWNER configures/rotates/verifies; OWNER/DEVELOPER read diagnostics and queue verified TEST events. URL must be HTTPS DNS hostname:443 without userinfo/query/fragment; no network/DNS request is performed. Network sender is absent; host mode DISABLED cannot verify or send, LOCAL_TEST proof is never accepted as a real endpoint verification. A03 notification status outbox and production DNS/IP pinning/HTTP transport remain planned. One-time secret, encrypted at rest. Version check prevents replaying a lost rotation; only one previous key retained for a 600-second overlap. No automatic retry.", "x-implementation-status": "local-notification-webhooks-disabled-host", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRevisionInput" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/webhook/test": { "post": { "operationId": "sendWebhookTest", "summary": "Enqueue endpoint.test for verified TEST destination", "tags": [ "Account Webhooks" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "202": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventQueued" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "description": "W04 control plane only. Account session, current membership and exact Origin/CSRF on mutations. OWNER configures/rotates/verifies; OWNER/DEVELOPER read diagnostics and queue verified TEST events. URL must be HTTPS DNS hostname:443 without userinfo/query/fragment; no network/DNS request is performed. Network sender is absent; host mode DISABLED cannot verify or send, LOCAL_TEST proof is never accepted as a real endpoint verification. A03 notification status outbox and production DNS/IP pinning/HTTP transport remain planned.", "x-implementation-status": "local-notification-webhooks-disabled-host", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRevisionInput" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/webhook/attempts": { "get": { "operationId": "listWebhookAttempts", "summary": "Read sanitized webhook attempts", "tags": [ "Account Webhooks" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAttemptPage" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "x-implementation-status": "local-notification-webhooks-disabled-host", "description": "W04 control plane only. Account session, current membership and exact Origin/CSRF on mutations. OWNER configures/rotates/verifies; OWNER/DEVELOPER read diagnostics and queue verified TEST events. URL must be HTTPS DNS hostname:443 without userinfo/query/fragment; no network/DNS request is performed. Network sender is absent; host mode DISABLED cannot verify or send, LOCAL_TEST proof is never accepted as a real endpoint verification. A03 notification status outbox and production DNS/IP pinning/HTTP transport remain planned. Signed scope-bound cursor, limit 1..100. No raw body, URL response, challenge, signature or secret. Pending count excludes expired events; each simulated attempt is marked LOCAL_TEST." } }, "/callbacks/twilio/message-status": { "post": { "operationId": "receiveTwilioMessageStatus", "summary": "Verify provider callback and persist delivery evidence", "tags": [ "Provider Callback" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "TwilioWebhookSignature": [] } ], "responses": { "204": { "description": "Accepted with no response body" }, "401": { "description": "Error; see api-contract.md for codes and retry semantics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error; see api-contract.md for codes and retry semantics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error; see api-contract.md for codes and retry semantics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Error; see api-contract.md for codes and retry semantics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected server error. Retry commands with the same Idempotency-Key; this is not proof of non-delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Sanitized callback proof/transport error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sanitized callback proof/transport error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Sanitized callback proof/transport error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Sanitized callback proof/transport error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Host defaults DISABLED (503). Trusted LOCAL_TEST/TEST-only attempt binding and encrypted verifier snapshot. Official SDK validates exact configured HTTPS URL and every form parameter. Strict scalar form, no duplicate keys, max 16 KiB. Durable proof commits before 204. No new notification is created from callback; no sender or lookup poller is enabled.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TwilioStatusCallback" } } } }, "x-implementation-status": "local-test-provider-receipts-disabled-host", "parameters": [ { "in": "query", "name": "binding", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Opaque per-attempt binding persisted before provider I/O; exact URL query signed." } ] } }, "/v1/installations/{installationId}": { "put": { "operationId": "upsertInstallation", "summary": "Register or rotate authenticated host installation", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Persisted scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Installation" } } } }, "413": { "description": "Request body exceeds 16 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "application/json is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/InstallationId" } ], "description": "Requires installations:read for GET and installations:write for PUT/DELETE. Service key belongs to backend only; host authenticates its user/installation. Token/config bound to credential application/environment. No B2C user lookup. Local A01/A05 implementation is opt-in, TEST FAKE only for new notifications; see api-handoff.md. No deployment or real provider readiness implied.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationInput" } } } }, "x-implementation-status": "local-test-only" }, "get": { "operationId": "getInstallation", "summary": "Read safe installation metadata", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Persisted scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Installation" } } } } }, "parameters": [ { "$ref": "#/components/parameters/InstallationId" } ], "description": "Requires installations:read for GET and installations:write for PUT/DELETE. Service key belongs to backend only; host authenticates its user/installation. Token/config bound to credential application/environment. No B2C user lookup. Local A01/A05 implementation is opt-in, TEST FAKE only for new notifications; see api-handoff.md. No deployment or real provider readiness implied.", "x-implementation-status": "local-test-only" }, "delete": { "operationId": "disableInstallation", "summary": "Disable own installation with version guard", "tags": [ "Data API" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Installation disabled; repeat own deletion is safe after authorization/version handling." } }, "parameters": [ { "$ref": "#/components/parameters/InstallationId" }, { "$ref": "#/components/parameters/InstallationVersion" } ], "description": "Requires installations:read for GET and installations:write for PUT/DELETE. Service key belongs to backend only; host authenticates its user/installation. Token/config bound to credential application/environment. No B2C user lookup. Local A01/A05 implementation is opt-in, TEST FAKE only for new notifications; see api-handoff.md. No deployment or real provider readiness implied.", "x-implementation-status": "local-test-only" } }, "/account/api/applications/{applicationId}/environments/{environment}/push-configurations": { "get": { "operationId": "listPushConfigurations", "summary": "List safe application push config metadata", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushConfigurationList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" } ], "description": "Account cookie, current organization membership. GET OWNER/DEVELOPER metadata only; PUT OWNER exact Origin + session CSRF and transactional recheck. API opt-in required, otherwise 503. One selected stored configuration per platform, maximum 8 per app/env. No provider I/O or real sender activation.", "x-implementation-status": "local-push-control-plane" } }, "/account/api/applications/{applicationId}/environments/{environment}/push-configurations/{configurationId}": { "put": { "operationId": "configurePushProvider", "summary": "Set scoped push credentials and route", "tags": [ "Account Webhooks" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushConfiguration" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/ConfigurationId" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushConfigurationInput" } } } }, "description": "Account cookie, current organization membership. GET OWNER/DEVELOPER metadata only; PUT OWNER exact Origin + session CSRF and transactional recheck. API opt-in required, otherwise 503. One selected stored configuration per platform, maximum 8 per app/env. No provider I/O or real sender activation.", "x-implementation-status": "local-push-control-plane" } }, "/account/api/organizations": { "get": { "operationId": "listAccountOrganizations", "summary": "List current organization memberships", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-implementation-status": "local-test-workspace" } }, "/account/api/applications/{applicationId}": { "get": { "operationId": "getAccountApplication", "summary": "Read application metadata within current membership", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" } ], "x-implementation-status": "local-test-workspace" } }, "/account/api/applications/{applicationId}/environments/{environment}/webhook/verification": { "post": { "operationId": "requestWebhookVerification", "summary": "Queue a fresh verification challenge for the current URL and signing key", "tags": [ "Account Webhooks" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "202": { "description": "Persisted result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventQueued" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "description": "W04 control plane only. Account session, current membership and exact Origin/CSRF on mutations. OWNER configures/rotates/verifies; OWNER/DEVELOPER read diagnostics and queue verified TEST events. URL must be HTTPS DNS hostname:443 without userinfo/query/fragment; no network/DNS request is performed. Network sender is absent; host mode DISABLED cannot verify or send, LOCAL_TEST proof is never accepted as a real endpoint verification. A03 notification status outbox and production DNS/IP pinning/HTTP transport remain planned.", "x-implementation-status": "local-notification-webhooks-disabled-host", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRevisionInput" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/sms-configurations": { "get": { "operationId": "listSmsConfigurations", "summary": "List safe application SMS config metadata", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsConfigurationList" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" } ], "description": "Application/environment-scoped Twilio settings. OWNER writes, members read metadata. No real sending, automatic activation or provider lookup. Target account/sender immutable; auth token write-only and encrypted; expected-version replay. Identity read budget: 120/minute. Response is no-store and contains no token or ciphertext.", "x-implementation-status": "local-sms-control-plane" } }, "/account/api/applications/{applicationId}/environments/{environment}/sms-configurations/{configurationId}": { "put": { "operationId": "configureSmsProvider", "summary": "Save scoped Twilio credentials and sender", "tags": [ "Account" ], "servers": [ { "url": "/", "description": "This deployment; check its enabled capabilities before use" }, { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST/FAKE stage" } ], "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Persisted scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsConfiguration" } } } }, "default": { "description": "Error; retry semantics in api-contract.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Scoped authorization, validation or admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/ConfigurationId" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsConfigurationInput" } } } }, "description": "Application/environment-scoped Twilio settings. OWNER writes, members read metadata. No real sending, automatic activation or provider lookup. Target account/sender immutable; auth token write-only and encrypted; expected-version replay. JSON body is bounded to 4096 bytes. At most eight stored records and one selection per application/environment. Identity write budget: 30/hour.", "x-implementation-status": "local-sms-control-plane" } }, "/account/api/profile/phone": { "post": { "operationId": "updateAccountContactPhone", "tags": [ "Account" ], "security": [ { "PlatformAccountCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "phone" ], "properties": { "phone": { "type": "string", "pattern": "^(?:|\\+[1-9][0-9]{7,14})$" } } } } } }, "responses": { "200": { "description": "Updated optional contact phone; never a login identity or consumer link. Empty string removes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "401": { "description": "Account session required" }, "403": { "description": "Origin/CSRF rejected" }, "422": { "description": "Invalid phone" } } } }, "/v1/verify/verifications": { "post": { "operationId": "createVerification", "summary": "Create a synthetic OTP challenge and reserve its sample success fee", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "201": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:write. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVerification" } } } } }, "get": { "operationId": "listVerifications", "summary": "Latest 50 project verifications and all-time Verify costs", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationList" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:read. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state." } }, "/v1/verify/verifications/{verificationId}": { "get": { "operationId": "getVerification", "summary": "Read current state; expiry is reconciled", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:read. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state." } }, "/v1/verify/verifications/{verificationId}/checks": { "post": { "operationId": "checkVerification", "summary": "Check a code; settle once on first success", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:write. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCheck" } } } } } }, "/v1/verify/verifications/{verificationId}/resend": { "post": { "operationId": "resendVerification", "summary": "Rotate a FAKE code without resetting TTL or attempts", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:write. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmptyMutation" } } } } } }, "/v1/verify/verifications/{verificationId}/cancel": { "post": { "operationId": "cancelVerification", "summary": "Cancel a pending challenge and release its hold", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:write. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmptyMutation" } } } } } }, "/v1/verify/verifications/{verificationId}/test-code": { "get": { "operationId": "readVerifyTestCode", "summary": "Read the synthetic FAKE inbox; not for production", "tags": [ "Verify TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyTestCode" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Required scope: verify:test-code:read. TEST only, explicit TEST usage billing opt-in; synthetic recipients only. TTL 300 seconds, 5 checks, 2 resends, 30-second cooldown. Standard success fee is a TEST fixture of 5 USD cents; affiliation and VERIFY overrides apply at creation. Replay returns the original receipt, not a refreshed state." } }, "/account/api/applications/{applicationId}/environments/{environment}/options": { "get": { "operationId": "getProjectOptions", "summary": "Read project configuration visibility", "description": "Cabinet session only. OWNER writes; members read. Never changes API admission, transport activation, credentials, existing jobs or money. Exact equal replay is harmless; stale changed version returns 409.", "tags": [ "Account" ], "security": [ { "PlatformAccountCookie": [] } ], "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] } } ], "responses": { "200": { "description": "Saved visibility options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOptions" } } } } } }, "put": { "operationId": "saveProjectOptions", "summary": "Save project configuration visibility", "description": "Cabinet session only. OWNER writes; members read. Never changes API admission, transport activation, credentials, existing jobs or money. Exact equal replay is harmless; stale changed version returns 409.", "tags": [ "Account" ], "security": [ { "PlatformAccountCookie": [] } ], "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Saved visibility options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOptions" } } } }, "409": { "description": "Changed stale version. Reload saved options before editing." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveProjectOptions" } } } } } }, "/v1/hailme/phone-otp/challenges": { "post": { "operationId": "hailMePhoneOtpCreateVerification", "summary": "Create a synthetic OTP challenge and reserve its sample success fee", "tags": [ "HailMe phone OTP TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "201": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HailMePhoneOtpVerification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "First-party HailMe TEST only. 300-second TTL and resend cooldown, five guesses, ten creates/hour per subject; immutable owner and idempotent operation. Codes require separate verify:test-code:read. LIVE is rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HailMePhoneOtpCreate" } } } } } }, "/v1/hailme/phone-otp/challenges/{verificationId}": { "get": { "operationId": "hailMePhoneOtpGetVerification", "summary": "Read current state; expiry is reconciled", "tags": [ "HailMe phone OTP TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HailMePhoneOtpVerification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "First-party HailMe TEST only. 300-second TTL and resend cooldown, five guesses, ten creates/hour per subject; immutable owner and idempotent operation. Codes require separate verify:test-code:read. LIVE is rejected." } }, "/v1/hailme/phone-otp/challenges/{verificationId}/checks": { "post": { "operationId": "hailMePhoneOtpCheckVerification", "summary": "Check a code; settle once on first success", "tags": [ "HailMe phone OTP TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HailMePhoneOtpVerification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "First-party HailMe TEST only. 300-second TTL and resend cooldown, five guesses, ten creates/hour per subject; immutable owner and idempotent operation. Codes require separate verify:test-code:read. LIVE is rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCheck" } } } } } }, "/v1/hailme/phone-otp/challenges/{verificationId}/cancel": { "post": { "operationId": "hailMePhoneOtpCancelVerification", "summary": "Cancel a pending challenge and release its hold", "tags": [ "HailMe phone OTP TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Persist a new UUID per mutation. Replay the exact request and key after uncertainty; never a new key to bypass policy." } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HailMePhoneOtpVerification" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "First-party HailMe TEST only. 300-second TTL and resend cooldown, five guesses, ten creates/hour per subject; immutable owner and idempotent operation. Codes require separate verify:test-code:read. LIVE is rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmptyMutation" } } } } } }, "/v1/hailme/phone-otp/challenges/{verificationId}/test-code": { "get": { "operationId": "hailMePhoneOtpReadVerifyTestCode", "summary": "Read the synthetic FAKE inbox; not for production", "tags": [ "HailMe phone OTP TEST" ], "security": [ { "PlatformServiceKey": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable operation receipt on mutations; current state on GET. Codes are absent except the scoped FAKE inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HailMePhoneOtpTestCode" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "TEST billing or budget blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden environment, scope or Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or terminal verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Strict input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or resend cooldown; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Verify unavailable or uncertain operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "First-party HailMe TEST only. 300-second TTL and resend cooldown, five guesses, ten creates/hour per subject; immutable owner and idempotent operation. Codes require separate verify:test-code:read. LIVE is rejected." } }, "/v1/telegram/test": { "get": { "operationId": "telegramTestGet", "summary": "List safe TEST connection and synthetic recipients", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:read. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestView" } } } }, "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telegram/test/bot": { "put": { "operationId": "telegramTestPutBot", "summary": "Configure simulated TEST bot", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:write. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestView" } } } }, "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestBotInput" } } } } } }, "/v1/telegram/test/links": { "post": { "operationId": "telegramTestPostLinks", "summary": "Create an expiring synthetic link", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:write. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestLinkCreated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestLinkInput" } } } } } }, "/v1/telegram/test/links/{linkId}": { "get": { "operationId": "telegramTestGetLinksLinkid", "summary": "Read link state without token", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:read. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestLink" } } } }, "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/telegram/test/links/{linkId}/simulate-start": { "post": { "operationId": "telegramTestPostLinksLinkidSimulateStart", "summary": "Simulate one private start update", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:write. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestLink" } } } }, "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestStartInput" } } } }, "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/telegram/test/links/{linkId}/confirm": { "post": { "operationId": "telegramTestPostLinksLinkidConfirm", "summary": "Explicitly confirm synthetic account association", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:write. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestLink" } } } }, "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyTelegramInput" } } } }, "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/telegram/test/recipients/{recipientId}/unlink": { "post": { "operationId": "telegramTestPostRecipientsRecipientidUnlink", "summary": "Revoke synthetic recipient generation", "description": "TEST/FAKE only, feature flag required. Backend bearer with telegram:write. No real Telegram transport.", "tags": [ "Telegram TEST" ], "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "TEST/FAKE result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestView" } } } }, "default": { "description": "Scoped validation, conflict, expiry, disabled module or authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramTestUnlinkInput" } } } }, "parameters": [ { "name": "recipientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/telegram/byoc": { "get": { "operationId": "telegramByocRead", "summary": "Read safe bot state and recipient references", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocView" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telegram/byoc/links": { "post": { "operationId": "telegramByocPostLinks", "summary": "Create private five-minute consent link", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformServiceKey": [] } ], "responses": { "201": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLinkCreated" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLinkInput" } } } } } }, "/v1/telegram/byoc/links/{linkId}": { "get": { "operationId": "telegramByocGetLinksLinkid", "summary": "Read current link state without its private start token", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLink" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/telegram/byoc/links/{linkId}/confirm": { "post": { "operationId": "telegramByocPostLinksLinkidConfirm", "summary": "Confirm the same reference after an authenticated private /start", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLink" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocConfirm" } } } } } }, "/v1/telegram/byoc/recipients/{recipientId}/unlink": { "post": { "operationId": "telegramByocPostRecipientsRecipientidUnlink", "summary": "Revoke consent and invalidate queued recipient versions", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformServiceKey": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocView" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "recipientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocUnlink" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc": { "get": { "operationId": "accountTelegramByocRead", "summary": "Read owner-only safe BYOC state", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocView" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" } ] }, "put": { "operationId": "accountTelegramByocSave", "summary": "Store or rotate encrypted write-only bot token without contacting Telegram", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocView" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocSave" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc/control": { "post": { "operationId": "accountTelegramByocControl", "summary": "Idempotent bot identity and owned webhook management", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocAction" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocControl" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc/links": { "post": { "operationId": "accountTelegramByocPostLinks", "summary": "Create private five-minute consent link", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLinkCreated" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLinkInput" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc/links/{linkId}": { "get": { "operationId": "accountTelegramByocGetLinksLinkid", "summary": "Read current link state without its private start token", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLink" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc/links/{linkId}/confirm": { "post": { "operationId": "accountTelegramByocPostLinksLinkidConfirm", "summary": "Confirm the same reference after an authenticated private /start", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocLink" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocConfirm" } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc/recipients/{recipientId}/unlink": { "post": { "operationId": "accountTelegramByocPostRecipientsRecipientidUnlink", "summary": "Revoke consent and invalidate queued recipient versions", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Staging only. Bot control I/O and outgoing messages are paused in this release. Backend telegram:read/write scopes or account OWNER required. No real recipient or bot is used for acceptance.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocView" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "name": "recipientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocUnlink" } } } } } }, "/hooks/telegram/{connectionId}/{credentialVersion}": { "post": { "operationId": "telegramByocCallback", "summary": "Receive authenticated Telegram private /start, /stop and bot block updates", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "HTTPS on the official stage host only, no Origin. Maximum64KiB/depth16 JSON; matching update_id replays are acknowledged without repeating work, conflicting bodies return409. Static secret is not a signature. Unsupported updates are ignored. No outbound reply.", "security": [ { "TelegramWebhookSecret": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramByocWebhookAck" } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "credentialVersion", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "update_id" ], "properties": { "update_id": { "type": "integer", "minimum": 0 }, "message": { "type": "object", "additionalProperties": true }, "my_chat_member": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/account/api/applications/{applicationId}/environments/{environment}/telegram/byoc/own-pilot/send": { "post": { "operationId": "accountTelegramOwnPilotSend", "summary": "Owner-only one-message real Telegram pilot with simulated TEST accounting", "tags": [ "Telegram BYOC" ], "servers": [ { "url": "https://platform-staging.hailme.app", "description": "Isolated TEST only" } ], "description": "Requires an operator permit for one project, bot and confirmed recipient. A durable one-attempt transport cap survives restart; uncertain responses must replay the same requestId. Production permits are control-only. No real payment.", "security": [ { "PlatformAccountCookie": [] } ], "responses": { "200": { "description": "Scoped result; not delivery/read evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEST_REAL_TELEGRAM_OWN_PILOT" ] }, "notificationId": { "type": "string", "format": "uuid" }, "replayed": { "type": "boolean" } }, "required": [ "mode", "notificationId", "replayed" ], "additionalProperties": false } } } }, "default": { "description": "Authorization, disabled flag, version/idempotency conflict, validation or bounded ingress error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApplicationId" }, { "$ref": "#/components/parameters/Environment" }, { "$ref": "#/components/parameters/CsrfToken" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" } }, "required": [ "requestId", "recipientId" ], "additionalProperties": false } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "requestId": { "type": "string", "minLength": 1 }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "requestId", "retryable" ] }, "CreateNotification": { "oneOf": [ { "$ref": "#/components/schemas/CreateSmsNotification" }, { "$ref": "#/components/schemas/CreatePushNotification" }, { "$ref": "#/components/schemas/CreateTelegramNotification" } ], "discriminator": { "propertyName": "channel", "mapping": { "SMS": "#/components/schemas/CreateSmsNotification", "PUSH": "#/components/schemas/CreatePushNotification", "TELEGRAM": "#/components/schemas/CreateTelegramNotification" } } }, "Notification": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "clientReference": { "type": "string" }, "submissionStatus": { "type": "string", "enum": [ "QUEUED", "DISPATCHING", "ACCEPTED", "FAILED", "UNKNOWN", "EXPIRED" ] }, "receiptStatus": { "type": "string", "enum": [ "NOT_AVAILABLE", "PENDING", "DELIVERED", "UNDELIVERED" ] }, "version": { "type": "integer", "format": "int64", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "providerMessageId": { "type": "string" }, "acceptedAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "receiptAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "failureCode": { "type": "string" }, "maskedRecipient": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "installationId": { "type": "string", "format": "uuid" }, "receiptMode": { "type": "string", "enum": [ "LOCAL_TEST", "REAL" ] }, "receiptConflict": { "type": "boolean" }, "receiptFailureCode": { "type": "string", "pattern": "^[0-9]{1,10}$" }, "reconciliationStatus": { "type": "string", "enum": [ "OPERATOR_REQUIRED", "LOOKUP_AVAILABLE" ] }, "estimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "smsEncoding": { "type": "string", "enum": [ "GSM_7", "UTF_16" ] }, "smsSegmentProfile": { "type": "string", "enum": [ "STANDARD_V1", "US_CA_TOLL_FREE_V1" ] }, "smsEstimateReconstructed": { "type": "boolean" }, "telegramRecipientId": { "type": "string", "format": "uuid" } }, "required": [ "id", "clientReference", "submissionStatus", "receiptStatus", "version", "createdAt", "updatedAt", "expiresAt", "channel" ], "description": "Versioned notification facts. ACCEPTED is provider acceptance; receipts do not prove reading. LOCAL_TEST evidence is simulated. acceptedAt/receiptAt are local observation timestamps. UNKNOWN never triggers blind resubmission." }, "TwilioStatusCallback": { "type": "object", "additionalProperties": { "type": "string" }, "required": [ "AccountSid", "MessageSid", "MessageStatus" ], "properties": { "AccountSid": { "type": "string" }, "MessageSid": { "type": "string" }, "MessageStatus": { "type": "string" }, "ErrorCode": { "type": "string" }, "NumSegments": { "type": "string", "pattern": "^[0-9]{1,4}$", "description": "Optional provider-reported segment count. Positive 1..1000 is retained once per verified attempt; zero is not yet available. LOCAL_TEST is simulation only." } }, "description": "Retain all vendor fields for official SDK signature validation; map statuses only after validation and attempt binding." }, "Template": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "locale": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "parameterSchema": { "type": "object", "description": "Optional bounded string parameter definitions; legacy templates return an empty object.", "additionalProperties": { "type": "object", "required": [ "type", "maxLength" ], "properties": { "type": { "type": "string", "enum": [ "string" ] }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 512 }, "description": { "type": "string", "maxLength": 200 }, "example": { "type": "string", "maxLength": 512 } } } }, "payloadKeys": { "type": "array", "maxItems": 16, "items": { "type": "string" }, "description": "Provider-neutral data keys; values and template body are visible only to the project owner." } }, "required": [ "id", "locale", "variables", "channel" ] }, "TemplateList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "items" ] }, "Usage": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time", "pattern": "Z$" }, "to": { "type": "string", "format": "date-time", "pattern": "Z$" }, "notifications": { "type": "integer", "format": "int64", "minimum": 0 }, "smsNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "pushNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "providerAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "smsSegments": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "smsSegmentsStatus": { "type": "string", "enum": [ "NOT_AVAILABLE", "PROVIDER_REPORTED", "PARTIAL" ] }, "channels": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "$ref": "#/components/schemas/ChannelUsage" } }, "knownEstimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedEstimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "estimatedAttemptSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "smsNotificationsMissingEstimate": { "type": "integer", "format": "int64", "minimum": 0 }, "smsAttemptsWithProviderReport": { "type": "integer", "format": "int64", "minimum": 0 }, "smsAttemptsWithoutProviderReport": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedReportedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedSmsAttemptsWithReport": { "type": "integer", "format": "int64", "minimum": 0 }, "segmentReportConflicts": { "type": "integer", "format": "int64", "minimum": 0 }, "legacyNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "legacyAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "estimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "billingStatus": { "type": "string", "enum": [ "NOT_AVAILABLE" ] }, "accountingSource": { "type": "string", "enum": [ "DURABLE_LEDGER_WITH_LEGACY_FALLBACK" ] }, "limits": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLimit" } }, "smsRoutes": { "type": "array", "items": { "$ref": "#/components/schemas/SmsRoutePolicy" } }, "telegramNotifications": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "from", "to", "notifications", "smsNotifications", "pushNotifications", "providerAttempts", "simulatedAttempts", "smsSegments", "smsSegmentsStatus", "channels", "telegramNotifications" ], "description": "Application/environment usage from durable admission/attempt accounting facts with unmatched legacy fallback. UTC [from,to); observations may arrive later and enrich historical provider-report totals. Calculated admission segments, attempted segments and provider-reported segments are distinct; LOCAL_TEST reports are simulated. No currency or invoice amount is fabricated. Original channel caps remain lifetime notification reservations; additional limits are calculated admission quotas, not a hard provider-spend ceiling." }, "Membership": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "format": "uuid" }, "organizationName": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "DEVELOPER" ] } }, "required": [ "organizationId", "organizationName", "role" ] }, "AccountSession": { "type": "object", "additionalProperties": false, "properties": { "identity": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "description": "Public registry UUID; never the internal Long host/membership ID." }, "displayName": { "type": "string" }, "maskedPhone": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "PLATFORM" ] }, "maskedEmail": { "type": "string", "nullable": true } }, "required": [ "id", "displayName", "maskedPhone", "kind", "maskedEmail" ] }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "csrfToken": { "type": "string", "minLength": 16 } }, "required": [ "identity", "memberships", "expiresAt", "csrfToken" ] }, "PhoneChallengeRequest": { "type": "object", "additionalProperties": false, "properties": { "phone": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, "required": [ "phone" ] }, "PhoneChallenge": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "challengeId", "expiresAt" ] }, "PhoneVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{4,8}$" } }, "required": [ "challengeId", "code" ] }, "ApplicationInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] }, "Application": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "enabled": { "type": "boolean" } }, "required": [ "name", "enabled" ] } }, "kind": { "type": "string", "enum": [ "FIRST_PARTY", "EXTERNAL" ] }, "flagship": { "type": "boolean" }, "smsCountryPolicy": { "type": "object", "nullable": true, "properties": { "blockedCountries": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "sourceRevision": { "type": "string" }, "importedAt": { "type": "string", "format": "date-time" } } } }, "required": [ "id", "organizationId", "name", "environments" ] }, "ApplicationList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "items" ] }, "ServiceKeyInput": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "notifications:write", "notifications:read", "templates:read", "usage:read", "installations:write", "installations:read" ] }, "minItems": 1, "maxItems": 6, "uniqueItems": true } }, "required": [ "label", "scopes" ] }, "ServiceKey": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "prefix": { "type": "string" }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "notifications:write", "notifications:read", "templates:read", "usage:read", "installations:write", "installations:read" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "revokedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "label", "prefix", "environment", "scopes", "createdAt" ] }, "ServiceKeyCreated": { "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/ServiceKey" }, "secret": { "type": "string", "minLength": 32 } }, "required": [ "key", "secret" ], "description": "One-time reveal only; never returned by subsequent GET. Lost response requires revoke/new key, not silent POST retry." }, "ServiceKeyList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceKey" } } }, "required": [ "items" ] }, "WebhookInput": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 }, "expectedVersion": { "type": "integer", "minimum": 0, "maximum": 999999999999999999 } }, "required": [ "url", "expectedVersion" ] }, "WebhookConfiguration": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri" }, "state": { "type": "string", "enum": [ "PENDING", "VERIFIED", "DISABLED" ] }, "activeSigningKeyId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "version": { "type": "integer", "minimum": 1 }, "deliveryMode": { "type": "string", "enum": [ "DISABLED", "LOCAL_TEST", "REAL" ] } }, "required": [ "url", "state", "updatedAt" ] }, "WebhookSigningKeyCreated": { "type": "object", "additionalProperties": false, "properties": { "keyId": { "type": "string" }, "secret": { "type": "string", "minLength": 32 }, "previousValidUntil": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "keyId", "secret" ], "description": "One-time signing secret reveal; verification challenge is enqueued for the current URL/config version." }, "EnvironmentConfiguration": { "type": "object", "additionalProperties": false, "properties": { "applicationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "enabled": { "type": "boolean" }, "webhook": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri" }, "state": { "type": "string", "enum": [ "PENDING", "VERIFIED", "DISABLED" ] }, "activeSigningKeyId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "version": { "type": "integer", "minimum": 1 }, "deliveryMode": { "type": "string", "enum": [ "DISABLED", "LOCAL_TEST", "REAL" ] } }, "required": [ "url", "state", "updatedAt" ], "nullable": true }, "webhookDeliveryMode": { "type": "string", "enum": [ "DISABLED", "LOCAL_TEST", "REAL" ] } }, "required": [ "applicationId", "environment", "enabled", "webhook" ] }, "NotificationPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ] }, "WebhookAttempt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "attemptNumber": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "httpStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "errorCode": { "type": "string" }, "deliveryMode": { "type": "string", "enum": [ "LOCAL_TEST", "DISABLED", "REAL" ] }, "completedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "kind": { "type": "string", "enum": [ "VERIFICATION", "TEST", "NOTIFICATION" ] }, "notificationId": { "type": "string", "format": "uuid" }, "notificationVersion": { "type": "integer", "format": "int64", "minimum": 1 }, "eventFinished": { "type": "boolean" }, "terminalReason": { "type": "string" }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "eventId", "attemptNumber", "state", "occurredAt" ] }, "WebhookAttemptPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } }, "nextCursor": { "type": "string", "nullable": true }, "deliveryMode": { "type": "string", "enum": [ "DISABLED", "LOCAL_TEST", "REAL" ] }, "pendingEvents": { "type": "integer", "minimum": 0 } }, "required": [ "items", "nextCursor" ] }, "EventQueued": { "type": "object", "additionalProperties": false, "properties": { "eventId": { "type": "string", "format": "uuid" } }, "required": [ "eventId" ] }, "NotificationEvent": { "type": "object", "additionalProperties": false, "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "type": { "type": "string", "enum": [ "notification.status.changed" ] }, "notification": { "$ref": "#/components/schemas/Notification" } }, "required": [ "eventId", "type", "occurredAt", "notification" ], "description": "Immutable transactional snapshot. Retries keep eventId/body; deliveries may duplicate or arrive out of order. Receiver deduplicates eventId and ignores lower notification.version. Fetch GET for authoritative current state." }, "VerificationEvent": { "type": "object", "additionalProperties": false, "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "type": { "type": "string", "enum": [ "endpoint.verification" ] }, "challenge": { "type": "string", "minLength": 16 } }, "required": [ "eventId", "type", "occurredAt", "challenge" ] }, "TestEvent": { "type": "object", "additionalProperties": false, "properties": { "eventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "type": { "type": "string", "enum": [ "endpoint.test" ] }, "message": { "type": "string" } }, "required": [ "eventId", "type", "occurredAt", "message" ] }, "WebhookEvent": { "oneOf": [ { "$ref": "#/components/schemas/NotificationEvent" }, { "$ref": "#/components/schemas/VerificationEvent" }, { "$ref": "#/components/schemas/TestEvent" } ], "description": "Outbound request to the integrator configured verified URL, signed using X-HailMe headers. Not a HailMe-hosted consumer API." }, "VerificationReply": { "type": "object", "additionalProperties": false, "properties": { "challenge": { "type": "string", "minLength": 16 } }, "required": [ "challenge" ] }, "CreateSmsNotification": { "type": "object", "additionalProperties": false, "properties": { "recipient": { "type": "object", "additionalProperties": false, "properties": { "phone": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$", "description": "E.164; synthetic examples are not approved recipients" } }, "required": [ "phone" ] }, "channel": { "type": "string", "enum": [ "SMS" ] }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128 }, "locale": { "type": "string", "minLength": 2, "maxLength": 32 }, "parameters": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 512 }, "description": "Keys and values further restricted by the approved application template" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "clientReference": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "recipient", "channel", "templateId", "locale", "parameters", "expiresAt", "clientReference" ], "description": "One SMS to a phone using application/env approved SMS template." }, "CreatePushNotification": { "type": "object", "additionalProperties": false, "properties": { "recipient": { "type": "object", "additionalProperties": false, "properties": { "installationId": { "type": "string", "format": "uuid" } }, "required": [ "installationId" ] }, "channel": { "type": "string", "enum": [ "PUSH" ] }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128 }, "locale": { "type": "string", "minLength": 2, "maxLength": 32 }, "parameters": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 512 }, "description": "Keys and values further restricted by the approved application template" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "clientReference": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "recipient", "channel", "templateId", "locale", "parameters", "expiresAt", "clientReference" ], "description": "One push to an active installation in credential application/env; compatible provider config and PUSH template required." }, "InstallationInput": { "type": "object", "additionalProperties": false, "properties": { "platform": { "type": "string", "enum": [ "ANDROID", "IOS" ] }, "provider": { "type": "string", "enum": [ "FCM", "APNS" ] }, "providerToken": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "applicationIdentifier": { "type": "string", "minLength": 1, "maxLength": 255 }, "locale": { "type": "string", "minLength": 2, "maxLength": 32 }, "expectedVersion": { "type": "integer", "minimum": 0 } }, "required": [ "platform", "provider", "providerToken", "applicationIdentifier", "locale", "expectedVersion" ], "description": "Backend consumer asserts authenticated host installation. expectedVersion=0 creates; updates use current version. Stale different token update returns 409; same canonical repeated PUT returns existing result." }, "Installation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ANDROID", "IOS" ] }, "provider": { "type": "string", "enum": [ "FCM", "APNS" ] }, "applicationIdentifier": { "type": "string" }, "locale": { "type": "string" }, "active": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "platform", "provider", "applicationIdentifier", "locale", "active", "version", "updatedAt" ] }, "PushConfigurationInput": { "type": "object", "additionalProperties": false, "properties": { "platform": { "type": "string", "enum": [ "ANDROID", "IOS" ] }, "provider": { "type": "string", "enum": [ "FCM", "APNS" ] }, "applicationIdentifier": { "type": "string", "minLength": 1, "maxLength": 255 }, "projectId": { "type": "string", "nullable": true }, "teamId": { "type": "string", "nullable": true }, "keyId": { "type": "string", "nullable": true }, "apnsEnvironment": { "type": "string", "enum": [ "SANDBOX", "PRODUCTION" ], "nullable": true }, "credentialMaterial": { "type": "string", "minLength": 1, "maxLength": 131072, "writeOnly": true, "nullable": true }, "enabled": { "type": "boolean" }, "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 999999999999999999 } }, "required": [ "platform", "provider", "applicationIdentifier", "enabled", "expectedVersion" ], "description": "OWNER write-only input. expectedVersion=0 creates; current version updates. Credential required at create; omit/null retains existing material. Target provider/platform/package/project/team/APNs environment immutable; new APNs key ID requires replacement .p8. Enabled is stored selection only, never dispatch readiness. APNs environment independent of logical TEST/LIVE.", "oneOf": [ { "properties": { "provider": { "enum": [ "FCM" ] } }, "required": [ "projectId" ] }, { "properties": { "provider": { "enum": [ "APNS" ] }, "platform": { "enum": [ "IOS" ] } }, "required": [ "teamId", "keyId", "apnsEnvironment" ] } ] }, "PushConfiguration": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ANDROID", "IOS" ] }, "provider": { "type": "string", "enum": [ "FCM", "APNS" ] }, "applicationIdentifier": { "type": "string" }, "projectId": { "type": "string" }, "teamId": { "type": "string" }, "keyId": { "type": "string" }, "apnsEnvironment": { "type": "string", "enum": [ "SANDBOX", "PRODUCTION" ] }, "enabled": { "type": "boolean" }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Scope/configuration-bound HMAC of canonical credential; contains no private material" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "version": { "type": "integer", "format": "int64", "minimum": 1 }, "credentialVersion": { "type": "integer", "format": "int64", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deliveryMode": { "type": "string", "enum": [ "DISABLED", "REAL" ] }, "validationStatus": { "type": "string", "enum": [ "LOCAL_ONLY" ] } }, "required": [ "id", "platform", "provider", "applicationIdentifier", "enabled", "updatedAt", "fingerprint", "version", "credentialVersion", "createdAt", "deliveryMode", "validationStatus" ], "description": "Metadata only; credentials never returned. Local key/declared metadata checks do not establish provider permissions, package ownership, APNs key scope or device delivery. enabled selects a dormant configuration; dispatcher and existing TEST routes/installations unchanged." }, "PushConfigurationList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PushConfiguration" } } }, "required": [ "items" ] }, "OrganizationList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "DEVELOPER" ] } }, "required": [ "id", "slug", "name", "role" ] } } }, "required": [ "items" ] }, "WebhookRevisionInput": { "type": "object", "additionalProperties": false, "properties": { "expectedVersion": { "type": "integer", "minimum": 0, "maximum": 999999999999999999 } }, "required": [ "expectedVersion" ] }, "AccountNotification": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "clientReference": { "type": "string" }, "submissionStatus": { "type": "string", "enum": [ "QUEUED", "DISPATCHING", "ACCEPTED", "FAILED", "UNKNOWN", "EXPIRED" ] }, "receiptStatus": { "type": "string", "enum": [ "NOT_AVAILABLE", "PENDING", "DELIVERED", "UNDELIVERED" ] }, "version": { "type": "integer", "format": "int64", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "acceptedAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "receiptAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "failureCode": { "type": "string" }, "maskedRecipient": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "installationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "FAKE", "TWILIO", "FCM", "APNS" ] }, "attemptCount": { "type": "integer", "format": "int64", "minimum": 0 }, "receiptMode": { "type": "string", "enum": [ "LOCAL_TEST", "REAL" ] }, "receiptConflict": { "type": "boolean" }, "receiptFailureCode": { "type": "string", "pattern": "^[0-9]{1,10}$" }, "reconciliationStatus": { "type": "string", "enum": [ "OPERATOR_REQUIRED", "LOOKUP_AVAILABLE" ] }, "estimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "smsEncoding": { "type": "string", "enum": [ "GSM_7", "UTF_16" ] }, "smsSegmentProfile": { "type": "string", "enum": [ "STANDARD_V1", "US_CA_TOLL_FREE_V1" ] }, "smsEstimateReconstructed": { "type": "boolean" }, "source": { "type": "string", "enum": [ "API", "CABINET", "GEO_TEST" ], "description": "Origin of the notification; all origins use the same scoped queue and status lifecycle." } }, "required": [ "id", "clientReference", "submissionStatus", "receiptStatus", "version", "createdAt", "updatedAt", "expiresAt", "channel", "provider", "attemptCount" ], "description": "Versioned notification facts. ACCEPTED is provider acceptance; receipts do not prove reading. LOCAL_TEST evidence is simulated. acceptedAt/receiptAt are local observation timestamps. UNKNOWN never triggers blind resubmission." }, "NotificationAttempt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer", "minimum": 1 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "observedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "recoveredAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "outcome": { "type": "string", "enum": [ "STARTED", "ACCEPTED", "UNKNOWN", "NOT_SUBMITTED", "REJECTED" ] }, "failureCode": { "type": "string" } }, "required": [ "id", "number", "startedAt", "outcome" ] }, "AccountNotificationDetail": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "clientReference": { "type": "string" }, "submissionStatus": { "type": "string", "enum": [ "QUEUED", "DISPATCHING", "ACCEPTED", "FAILED", "UNKNOWN", "EXPIRED" ] }, "receiptStatus": { "type": "string", "enum": [ "NOT_AVAILABLE", "PENDING", "DELIVERED", "UNDELIVERED" ] }, "version": { "type": "integer", "format": "int64", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "acceptedAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "receiptAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "failureCode": { "type": "string" }, "maskedRecipient": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "installationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "FAKE", "TWILIO", "FCM", "APNS" ] }, "attemptCount": { "type": "integer", "format": "int64", "minimum": 0 }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationAttempt" } }, "receiptMode": { "type": "string", "enum": [ "LOCAL_TEST", "REAL" ] }, "receiptConflict": { "type": "boolean" }, "receiptFailureCode": { "type": "string", "pattern": "^[0-9]{1,10}$" }, "reconciliationStatus": { "type": "string", "enum": [ "OPERATOR_REQUIRED", "LOOKUP_AVAILABLE" ] }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptEvidence" } }, "estimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "smsEncoding": { "type": "string", "enum": [ "GSM_7", "UTF_16" ] }, "smsSegmentProfile": { "type": "string", "enum": [ "STANDARD_V1", "US_CA_TOLL_FREE_V1" ] }, "smsEstimateReconstructed": { "type": "boolean" }, "source": { "type": "string", "enum": [ "API", "CABINET", "GEO_TEST" ], "description": "Origin of the notification; all origins use the same scoped queue and status lifecycle." } }, "required": [ "id", "clientReference", "submissionStatus", "receiptStatus", "version", "createdAt", "updatedAt", "expiresAt", "channel", "provider", "attemptCount", "attempts", "receipts" ], "description": "Versioned notification facts. ACCEPTED is provider acceptance; receipts do not prove reading. LOCAL_TEST evidence is simulated. acceptedAt/receiptAt are local observation timestamps. UNKNOWN never triggers blind resubmission." }, "AccountNotificationPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountNotification" } }, "nextCursor": { "type": "string", "nullable": true }, "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true }, "periodBasis": { "type": "string", "enum": [ "NOTIFICATION_CREATION_TIME" ] }, "filters": { "$ref": "#/components/schemas/AccountUsageFilters" } }, "required": [ "items", "nextCursor", "from", "to", "periodBasis", "filters" ] }, "ChannelUsage": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "notifications": { "type": "integer", "format": "int64", "minimum": 0 }, "providerAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "configured": { "type": "boolean" }, "admissionEnabled": { "type": "boolean" }, "capUnit": { "type": "string", "enum": [ "NOTIFICATIONS" ] }, "capWindow": { "type": "string", "enum": [ "LIFETIME" ] }, "cap": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "reserved": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true } }, "required": [ "channel", "notifications", "providerAttempts", "simulatedAttempts", "configured", "admissionEnabled", "capUnit", "capWindow", "cap", "reserved" ] }, "ReceiptEvidence": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "attemptId": { "type": "string", "format": "uuid" }, "providerStatus": { "type": "string", "enum": [ "ACCEPTED", "SCHEDULED", "QUEUED", "SENDING", "SENT", "DELIVERED", "UNDELIVERED", "FAILED", "CANCELED" ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "mode": { "type": "string", "enum": [ "LOCAL_TEST", "REAL" ] }, "conflict": { "type": "boolean" }, "failureCode": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, "required": [ "id", "attemptId", "providerStatus", "observedAt", "mode", "conflict" ] }, "UsageLimit": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "unit": { "type": "string", "enum": [ "NOTIFICATIONS", "SMS_SEGMENTS" ] }, "window": { "type": "string", "enum": [ "LIFETIME", "UTC_DAY", "UTC_MONTH" ] }, "capacity": { "type": "integer", "format": "int64", "minimum": 0 }, "reserved": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "remaining": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "bucketStart": { "type": "string", "format": "date-time", "pattern": "Z$" }, "bucketEnd": { "type": "string", "format": "date-time", "pattern": "Z$", "nullable": true }, "basis": { "type": "string", "enum": [ "CALCULATED_ADMISSION_TEXT", "ADMITTED_NOTIFICATIONS" ] } }, "required": [ "channel", "unit", "window", "capacity", "reserved", "remaining", "bucketStart", "bucketEnd", "basis" ] }, "SmsRoutePolicy": { "type": "object", "additionalProperties": false, "properties": { "configurationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "FAKE", "TWILIO" ] }, "segmentProfile": { "type": "string", "enum": [ "STANDARD_V1", "US_CA_TOLL_FREE_V1" ] }, "countryCodes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "minItems": 1 }, "maxSegments": { "type": "integer", "minimum": 1, "maximum": 1000 }, "admissionEnabled": { "type": "boolean" } }, "required": [ "configurationId", "provider", "segmentProfile", "countryCodes", "maxSegments", "admissionEnabled" ] }, "SmsConfigurationInput": { "type": "object", "additionalProperties": false, "properties": { "accountSid": { "type": "string", "pattern": "^AC[0-9a-fA-F]{32}$" }, "senderType": { "type": "string", "enum": [ "ADDRESS", "MESSAGING_SERVICE" ] }, "sender": { "type": "string", "minLength": 1, "maxLength": 34 }, "authToken": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!-~]+$", "nullable": true, "writeOnly": true }, "enabled": { "type": "boolean" }, "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 999999999999999999 } }, "required": [ "accountSid", "senderType", "sender", "enabled", "expectedVersion" ], "description": "OWNER-only Twilio settings. Token required at creation; omit/null retains it on edit. Account and sender immutable. Expected version 0 creates; exact replay is idempotent. Stored selection never activates LIVE or delivery. Local validation only; no provider calls." }, "SmsConfiguration": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Scope/configuration-bound HMAC of canonical credential; contains no private material" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "version": { "type": "integer", "format": "int64", "minimum": 1 }, "credentialVersion": { "type": "integer", "format": "int64", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deliveryMode": { "type": "string", "enum": [ "DISABLED", "REAL" ] }, "validationStatus": { "type": "string", "enum": [ "LOCAL_ONLY" ] }, "accountSid": { "type": "string", "pattern": "^AC[0-9a-fA-F]{32}$" }, "senderType": { "type": "string", "enum": [ "ADDRESS", "MESSAGING_SERVICE" ] }, "sender": { "type": "string", "minLength": 1, "maxLength": 34 }, "provider": { "type": "string", "enum": [ "TWILIO" ] } }, "required": [ "id", "enabled", "fingerprint", "updatedAt", "version", "credentialVersion", "createdAt", "deliveryMode", "validationStatus", "accountSid", "senderType", "sender", "provider" ], "description": "Scoped Twilio metadata only; Auth Token and encrypted storage never returned. LOCAL_ONLY does not prove provider authorization." }, "SmsConfigurationList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SmsConfiguration" } } } }, "EmailChallenge": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "challengeId", "expiresAt" ] }, "EmailChallengeRequest": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } } }, "EmailVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{4,8}$" } }, "required": [ "challengeId", "code" ] }, "AccountTestUsageCosts": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "AVAILABLE" ] }, "mode": { "type": "string", "enum": [ "SANDBOX" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "periodBasis": { "type": "string", "enum": [ "NOTIFICATION_ADMISSION_TIME" ] }, "chargedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "reservedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "releasedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "pricedNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "testUsageBillingEnabled": { "type": "boolean" }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "byDay": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/components/schemas/AccountUsageDayCosts" } }, "byChannel": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/components/schemas/AccountUsageChannelCosts" } } }, "required": [ "status", "mode", "currency", "periodBasis", "chargedMinor", "reservedMinor", "releasedMinor", "pricedNotifications", "testUsageBillingEnabled", "timezone", "byDay", "byChannel" ], "description": "OWNER-only recorded TEST/FAKE project costs. Integer USD cents, scoped by notification admission in the parent UTC half-open period. Existing price snapshots only; no repricing, subscription/top-up allocation or read-triggered charges. UNKNOWN remains reserved. Daily UTC rows include empty days and only the selected part of boundary days, ascending by date. Channel rows include selected channels (SMS and/or PUSH), including zero totals. Each breakdown independently sums to the parent amounts and pricedNotifications; all derive from the same ledger snapshot." }, "AccountUsageCostsUnavailable": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "OWNER_REQUIRED", "TEST_ONLY", "DISABLED" ] } }, "required": [ "status" ] }, "AccountUsage": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time", "pattern": "Z$" }, "to": { "type": "string", "format": "date-time", "pattern": "Z$" }, "notifications": { "type": "integer", "format": "int64", "minimum": 0 }, "smsNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "pushNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "providerAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "smsSegments": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "smsSegmentsStatus": { "type": "string", "enum": [ "NOT_AVAILABLE", "PROVIDER_REPORTED", "PARTIAL" ] }, "channels": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/components/schemas/ChannelUsage" } }, "knownEstimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedEstimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "estimatedAttemptSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "smsNotificationsMissingEstimate": { "type": "integer", "format": "int64", "minimum": 0 }, "smsAttemptsWithProviderReport": { "type": "integer", "format": "int64", "minimum": 0 }, "smsAttemptsWithoutProviderReport": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedReportedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0 }, "simulatedSmsAttemptsWithReport": { "type": "integer", "format": "int64", "minimum": 0 }, "segmentReportConflicts": { "type": "integer", "format": "int64", "minimum": 0 }, "legacyNotifications": { "type": "integer", "format": "int64", "minimum": 0 }, "legacyAttempts": { "type": "integer", "format": "int64", "minimum": 0 }, "estimatedSmsSegments": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "billingStatus": { "type": "string", "enum": [ "NOT_AVAILABLE", "TEST_SANDBOX" ] }, "accountingSource": { "type": "string", "enum": [ "DURABLE_LEDGER_WITH_LEGACY_FALLBACK" ] }, "limits": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLimit" } }, "smsRoutes": { "type": "array", "items": { "$ref": "#/components/schemas/SmsRoutePolicy" } }, "billing": { "oneOf": [ { "$ref": "#/components/schemas/AccountTestUsageCosts" }, { "$ref": "#/components/schemas/AccountUsageCostsUnavailable" } ] }, "filters": { "$ref": "#/components/schemas/AccountUsageFilters" }, "telegramNotifications": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "from", "to", "notifications", "smsNotifications", "pushNotifications", "providerAttempts", "simulatedAttempts", "smsSegments", "smsSegmentsStatus", "channels", "billingStatus", "billing", "filters", "telegramNotifications" ], "description": "Account project usage with OWNER-only TEST/FAKE recorded costs. Public service-key Usage remains unchanged. Foreign members receive 404; developers receive counters with OWNER_REQUIRED and no financial values. Optional account-only channel/source filters apply to operation, attempt, SMS report and recorded cost totals. The response echoes the applied filters. Source follows retained trusted admission namespaces; unclassified history is included only in ALL. Channel breakdowns include only selected channels. Admission caps, additional limits and budgets remain project-wide metadata." }, "AccountUsageDayCosts": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "chargedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "reservedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "releasedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "pricedNotifications": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "date", "chargedMinor", "reservedMinor", "releasedMinor", "pricedNotifications" ] }, "AccountUsageChannelCosts": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string", "enum": [ "SMS", "PUSH", "TELEGRAM" ] }, "chargedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "reservedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "releasedMinor": { "type": "integer", "format": "int64", "minimum": 0 }, "pricedNotifications": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "channel", "chargedMinor", "reservedMinor", "releasedMinor", "pricedNotifications" ] }, "AccountUsageFilters": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string", "enum": [ "ALL", "SMS", "PUSH" ] }, "source": { "type": "string", "enum": [ "ALL", "API", "CABINET", "GEO_TEST" ] } }, "required": [ "channel", "source" ] }, "CreateVerification": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "recipient": { "type": "string", "pattern": "^test:[A-Za-z0-9_-]{1,48}$", "example": "test:customer-001" }, "purpose": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$", "example": "signup" } }, "required": [ "channel", "recipient", "purpose" ], "additionalProperties": false }, "VerifyCheck": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Secret code. Never log or include it in a URL." } }, "required": [ "code" ], "additionalProperties": false }, "VerifyEmptyMutation": { "type": "object", "maxProperties": 0, "additionalProperties": false }, "VerifyBilling": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "rateVersion": { "type": "string" }, "unit": { "type": "string", "enum": [ "UNIQUE_SUCCESSFUL_VERIFICATION" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Immutable sample price snapshot in USD cents." }, "status": { "type": "string", "enum": [ "HELD", "SETTLED", "RELEASED" ] }, "providerCostMinor": { "type": "integer", "enum": [ 0 ] }, "providerCostMode": { "type": "string", "enum": [ "FAKE_ZERO_NOT_PROVIDER_PRICE" ] }, "feeSource": { "type": "string" }, "affiliated": { "type": "boolean" }, "organizationPolicyVersion": { "type": "integer" }, "projectPolicyVersion": { "type": "integer" } }, "required": [ "mode", "currency", "rateVersion", "unit", "amountMinor", "status", "providerCostMinor", "providerCostMode", "feeSource", "affiliated", "organizationPolicyVersion", "projectPolicyVersion" ] }, "Verification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "TEST" ] }, "provider": { "type": "string", "enum": [ "FAKE" ] }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "recipient": { "type": "string" }, "purpose": { "type": "string" }, "source": { "type": "string", "enum": [ "API", "CABINET" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "EXPIRED", "CANCELLED", "LOCKED" ] }, "attemptsRemaining": { "type": "integer", "minimum": 0, "maximum": 5 }, "resendsRemaining": { "type": "integer", "minimum": 0, "maximum": 2 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "resendAvailableAt": { "type": "string", "format": "date-time" }, "billing": { "$ref": "#/components/schemas/VerifyBilling" }, "replayed": { "type": "boolean" }, "valid": { "type": "boolean", "description": "Present on check results only." } }, "required": [ "id", "environment", "provider", "channel", "recipient", "purpose", "source", "status", "attemptsRemaining", "resendsRemaining", "createdAt", "expiresAt", "resendAvailableAt", "billing", "replayed" ] }, "VerificationList": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Verification" } }, "total": { "type": "integer", "minimum": 0 }, "chargedMinor": { "type": "integer", "minimum": 0 }, "reservedMinor": { "type": "integer", "minimum": 0 }, "releasedMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "rateVersion": { "type": "string" }, "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "limit": { "type": "integer", "enum": [ 50 ] }, "sampleSuccessFeeMinor": { "type": "integer", "enum": [ 5 ] } }, "required": [ "items", "total", "chargedMinor", "reservedMinor", "releasedMinor", "currency", "rateVersion" ] }, "VerifyTestCode": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "verificationId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "FAKE test inbox only. Never exposed by ordinary create/list/status." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "mode", "verificationId", "code", "expiresAt" ] }, "ProjectOptions": { "type": "object", "required": [ "applicationId", "environment", "version", "features", "availableOptions", "effect" ], "properties": { "applicationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "version": { "type": "integer", "minimum": 0 }, "features": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "SMS", "PUSH", "EMAIL", "WHATSAPP", "TELEGRAM", "SIGNAL", "VERIFY", "GEO", "WEBHOOKS" ] } }, "availableOptions": { "type": "array", "items": { "type": "string" } }, "effect": { "type": "string", "enum": [ "CONFIGURATION_VISIBILITY_ONLY" ] } } }, "SaveProjectOptions": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "features" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0 }, "features": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "SMS", "PUSH", "EMAIL", "WHATSAPP", "TELEGRAM", "SIGNAL", "VERIFY", "GEO", "WEBHOOKS" ] } } } }, "HailMePhoneOtpCreate": { "type": "object", "additionalProperties": false, "required": [ "recipient", "deliveryRoute", "language", "clientPlatform", "appHash" ], "properties": { "recipient": { "type": "string", "pattern": "^test:hm_[a-f0-9]{40}$", "description": "HMAC-derived synthetic subject. Never an E.164 phone or mobile user ID." }, "deliveryRoute": { "type": "string", "enum": [ "LEGACY_SMS", "TWILIO_VERIFY" ], "description": "FAKE route simulation only; no Twilio request is made." }, "language": { "type": "string", "enum": [ "EN", "ES", "PT", "RU", "UK", "HE" ] }, "clientPlatform": { "type": "string", "enum": [ "ANDROID", "IOS", "UNKNOWN" ] }, "appHash": { "type": "string", "pattern": "^([A-Za-z0-9_-]{11})?$" } } }, "HailMePhoneOtpVerification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "TEST" ] }, "provider": { "type": "string", "enum": [ "FAKE" ] }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "recipient": { "type": "string" }, "purpose": { "type": "string" }, "source": { "type": "string", "enum": [ "API", "CABINET" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "EXPIRED", "CANCELLED", "LOCKED" ] }, "attemptsRemaining": { "type": "integer", "minimum": 0, "maximum": 5 }, "resendsRemaining": { "type": "integer", "minimum": 0, "maximum": 2 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "resendAvailableAt": { "type": "string", "format": "date-time" }, "billing": { "$ref": "#/components/schemas/VerifyBilling" }, "replayed": { "type": "boolean" }, "valid": { "type": "boolean", "description": "Present on check results only." }, "profile": { "type": "string", "enum": [ "HAILME_PHONE_V1" ] }, "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "deliveryRoute": { "type": "string", "enum": [ "LEGACY_SMS", "TWILIO_VERIFY" ] }, "cooldownSeconds": { "type": "integer", "enum": [ 300 ] }, "expiresInSeconds": { "type": "integer", "enum": [ 300 ], "description": "Original challenge lifetime; use expiresAt to calculate remaining validity." }, "realDelivery": { "type": "boolean", "enum": [ false ] } }, "required": [ "id", "environment", "provider", "channel", "recipient", "purpose", "source", "status", "attemptsRemaining", "resendsRemaining", "createdAt", "expiresAt", "resendAvailableAt", "billing", "replayed", "profile", "mode", "deliveryRoute", "cooldownSeconds", "expiresInSeconds", "realDelivery" ] }, "HailMePhoneOtpTestCode": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "verificationId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "FAKE test inbox only. Never exposed by ordinary create/list/status." }, "expiresAt": { "type": "string", "format": "date-time" }, "profile": { "type": "string", "enum": [ "HAILME_PHONE_V1" ] }, "deliveryRoute": { "type": "string", "enum": [ "LEGACY_SMS", "TWILIO_VERIFY" ] }, "cooldownSeconds": { "type": "integer", "enum": [ 300 ] }, "expiresInSeconds": { "type": "integer", "enum": [ 300 ], "description": "Original challenge lifetime; use expiresAt to calculate remaining validity." }, "realDelivery": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string", "description": "Synthetic inbox only. Never forwarded by the mobile HTTP API." }, "messageTemplateOwner": { "type": "string", "enum": [ "PLATFORM", "PROVIDER_SIMULATED" ] } }, "required": [ "mode", "verificationId", "code", "expiresAt", "profile", "deliveryRoute", "cooldownSeconds", "expiresInSeconds", "realDelivery", "message", "messageTemplateOwner" ] }, "CreateTelegramNotification": { "type": "object", "additionalProperties": false, "properties": { "recipient": { "type": "object", "additionalProperties": false, "properties": { "telegramRecipientId": { "type": "string", "format": "uuid" } }, "required": [ "telegramRecipientId" ] }, "channel": { "type": "string", "enum": [ "TELEGRAM" ] }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128 }, "locale": { "type": "string", "minLength": 2, "maxLength": 32 }, "parameters": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 512 }, "description": "Keys and values further restricted by the approved application template" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "RFC 3339 UTC timestamp ending in Z" }, "clientReference": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "recipient", "channel", "templateId", "locale", "parameters", "expiresAt", "clientReference" ], "description": "Isolated TEST/FAKE only. Confirm a synthetic recipient through /v1/telegram/test before sending. LIVE and real chat IDs are refused." }, "TelegramTestBotInput": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "enabled": { "type": "boolean" }, "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "label", "enabled", "expectedVersion" ] }, "TelegramTestLinkInput": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "pattern": "^test:[A-Za-z0-9._-]{1,64}$" }, "locale": { "type": "string", "maxLength": 32 } }, "required": [ "requestId", "reference", "locale" ] }, "TelegramTestStartInput": { "type": "object", "additionalProperties": false, "properties": { "testToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "fakeChat": { "type": "string", "pattern": "^fake:[A-Za-z0-9._:-]{1,64}$", "writeOnly": true }, "updateId": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "testToken", "fakeChat", "updateId" ] }, "TelegramTestUnlinkInput": { "type": "object", "additionalProperties": false, "properties": { "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "expectedVersion" ] }, "TelegramTestLink": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PENDING", "MATCHED", "CONFIRMED", "EXPIRED" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "TEST_FAKE" ] } }, "required": [ "id", "recipientId", "state", "expiresAt", "mode" ] }, "TelegramTestLinkCreated": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PENDING", "MATCHED", "CONFIRMED", "EXPIRED" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "testToken": { "type": "string", "description": "Opaque creation token. Keep private; available only in this idempotent creation response." } }, "required": [ "id", "recipientId", "state", "expiresAt", "mode", "testToken" ] }, "TelegramTestRecipient": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "locale": { "type": "string" }, "active": { "type": "boolean" }, "version": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "id", "reference", "locale", "active", "version" ] }, "TelegramTestView": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "TEST_FAKE" ] }, "connected": { "type": "boolean" }, "botVersion": { "type": "integer", "format": "int64", "minimum": 0 }, "label": { "type": "string" }, "realTelegramConnected": { "type": "boolean", "enum": [ false ] }, "recipients": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/TelegramTestRecipient" } } }, "required": [ "enabled", "mode", "connected", "botVersion", "label", "realTelegramConnected", "recipients" ] }, "EmptyTelegramInput": { "type": "object", "additionalProperties": false, "properties": {} }, "TelegramByocSave": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "token": { "type": "string", "nullable": true, "writeOnly": true, "pattern": "^[1-9][0-9]{5,15}:[A-Za-z0-9_-]{20,200}$", "description": "New token or null to retain the existing credential. Never returned." }, "enabled": { "type": "boolean" }, "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "requestId", "label", "token", "enabled", "expectedVersion" ], "additionalProperties": false }, "TelegramByocControl": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "VERIFY", "REGISTER", "STATUS", "DISCONNECT" ] }, "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "requestId", "kind", "expectedVersion" ], "additionalProperties": false }, "TelegramByocAction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "UNKNOWN", "STALE" ] }, "code": { "type": "string" } }, "required": [ "id", "status" ], "additionalProperties": false }, "TelegramByocLinkInput": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$", "description": "Opaque application user reference; do not use phone/email." }, "locale": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "maxLength": 32 } }, "required": [ "requestId", "reference", "locale" ], "additionalProperties": false }, "TelegramByocConfirm": { "type": "object", "properties": { "reference": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$", "description": "Opaque application user reference; do not use phone/email." } }, "required": [ "reference" ], "additionalProperties": false }, "TelegramByocUnlink": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "expectedVersion" ], "additionalProperties": false }, "TelegramByocLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PENDING", "MATCHED", "CONFIRMED", "EXPIRED", "CANCELLED" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "recipientId", "state", "expiresAt" ], "additionalProperties": false }, "TelegramByocLinkCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PENDING", "MATCHED", "CONFIRMED", "EXPIRED", "CANCELLED" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "startUrl": { "type": "string", "format": "uri", "description": "Private bearer capability, five-minute TTL; creation replay returns the same URL. Never put into logs." }, "outboundEnabled": { "type": "boolean" } }, "required": [ "id", "recipientId", "state", "expiresAt", "startUrl", "outboundEnabled" ], "additionalProperties": false }, "TelegramByocView": { "type": "object", "properties": { "available": { "type": "boolean" }, "configured": { "type": "boolean" }, "controlIoEnabled": { "type": "boolean" }, "outboundEnabled": { "type": "boolean" }, "mode": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "state": { "type": "string" }, "version": { "type": "integer", "format": "int64", "minimum": 0 }, "credentialVersion": { "type": "integer", "format": "int64", "minimum": 0 }, "hasToken": { "type": "boolean" }, "username": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "pendingUpdates": { "type": "integer", "format": "int64", "minimum": 0 }, "lastCode": { "type": "string" }, "botLimitPerSecond": { "type": "integer" }, "privateChatLimitPerSecond": { "type": "integer" }, "pendingActionId": { "type": "string", "format": "uuid" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "locale": { "type": "string" }, "active": { "type": "boolean" }, "version": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "id", "reference", "locale", "active", "version" ], "additionalProperties": false }, "maxItems": 200 }, "pilotReference": { "type": "string" }, "pilotExpiresAt": { "type": "string", "format": "date-time" }, "pilotActive": { "type": "boolean" }, "pilotMaxTransportAttempts": { "type": "integer", "enum": [ 1 ] }, "pilotAttemptConsumed": { "type": "boolean" } }, "required": [ "available", "configured", "controlIoEnabled", "outboundEnabled", "mode" ], "additionalProperties": false }, "TelegramByocWebhookAck": { "type": "object", "properties": { "outcome": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "outcome", "replayed" ], "additionalProperties": false } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable across retries. Same canonical payload replays original result; changed payload returns 409. Lookup precedes expectedVersion." }, "OrganizationId": { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "ApplicationId": { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Environment": { "name": "environment", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] } }, "KeyId": { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "NotificationId": { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "CsrfToken": { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16 } }, "Origin": { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must match configured trusted account origin, independent of untrusted forwarded headers" }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "From": { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "Z$" }, "description": "Use together with to; omitted pair uses last 24 hours. UTC Z only; max 31 days; from inclusive." }, "To": { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "Z$" }, "description": "Use together with from; UTC Z only; to exclusive and no later than database now." }, "InstallationId": { "name": "installationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "ConfigurationId": { "name": "configurationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "InstallationVersion": { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Quoted current installation version; protects logout/delete from a stale token lifecycle event." } }, "securitySchemes": { "PlatformServiceKey": { "type": "http", "scheme": "bearer", "description": "Backend-only credential scoped to application/environment and explicit API scopes; not a browser/mobile credential." }, "PlatformAccountCookie": { "type": "apiKey", "in": "cookie", "name": "hailme_platform_session", "description": "HttpOnly Secure host-only account-purpose session. Membership checks plus Origin/CSRF for mutations. Not staff/mobile cookie." }, "TwilioWebhookSignature": { "type": "apiKey", "in": "header", "name": "X-Twilio-Signature", "description": "Official SDK request signature validation with actual URL, all form fields and allowlisted provider account." }, "TelegramWebhookSecret": { "type": "apiKey", "in": "header", "name": "X-Telegram-Bot-Api-Secret-Token", "description": "Generated static webhook secret, constant-time checked and scoped to connection/credential version. Not a cryptographic signature. No browser Origin accepted." } } }, "externalDocs": { "url": "https://platform-staging.hailme.app/docs", "description": "Integration and SDK guides on the isolated TEST stage" } }