{ "openapi": "3.1.1", "info": { "title": "SMSGO API", "version": "1.1.0", "description": "SMSGO REST API v1. JSON over HTTPS, Bearer API keys, Idempotency-Key on every POST. Recipients must be Turkish mobile numbers in E.164 (+905XXXXXXXXX); landlines, 850/444/800 numbers, unallocated mobile prefixes and foreign numbers are refused with a reason. Accounts pay either from a money wallet (tariff) or with SMS credits (by default 1 credit per message, whatever its length). Human-readable reference: /developers/docs. Prose contract: 04_API_CONTRACT.md." }, "servers": [ { "url": "/api/v1", "description": "Deployment HTTPS host; unaffected by web slugs" } ], "security": [ { "ApiKey": [] } ], "paths": { "/messages": { "post": { "operationId": "sendMessage", "summary": "Send one message", "x-required-scope": "messages:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Account+method+path scoped; successful replay retained for at least 30 days." } ], "responses": { "202": { "description": "Durably accepted; not delivery confirmation", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Location": { "schema": { "type": "string" }, "description": "GET resource URL." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "True on replay." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessage" } } } }, "tags": [ "Messages" ], "description": "Validates, prices (or takes SMS credits) and queues one message. 202 means durably accepted, not delivered." }, "get": { "operationId": "listMessages", "summary": "List messages", "x-required-scope": "messages:read", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "submitting", "accepted", "unknown", "delivered", "failed", "undeliverable", "expired", "canceled" ] } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sms", "whatsapp", "viber" ] } }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "Z$" } }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "Z$" } }, { "name": "client_reference", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Messages" ], "description": "Newest first, cursor paginated. Filters define the cursor scope." } }, "/message-batches": { "post": { "operationId": "sendBatch", "summary": "Send a batch", "x-required-scope": "messages:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Account+method+path scoped; successful replay retained for at least 30 days." } ], "responses": { "202": { "description": "Durably accepted; not delivery confirmation", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Location": { "schema": { "type": "string" }, "description": "GET resource URL." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "True on replay." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAcceptedResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBatch" } } } }, "tags": [ "Batches" ], "description": "Up to 100 messages accepted or rejected as a whole; one invalid item rejects the batch with its field path (messages.N.field)." } }, "/messages/{id}": { "get": { "operationId": "getMessage", "summary": "Get a message", "x-required-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Messages" ], "description": "Current status, billing status, amounts or credits and the platform failure code." } }, "/message-batches/{id}": { "get": { "operationId": "getBatch", "summary": "Get a batch", "x-required-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Batches" ], "description": "Counts by status and a cursor-paginated page of its messages." } }, "/messages/{id}/cancel": { "post": { "operationId": "cancelMessage", "summary": "Cancel a queued message", "x-required-scope": "messages:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Account+method+path scoped; successful replay retained for at least 30 days." } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "True on replay." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Messages" ], "description": "Only while status is queued (e.g. scheduled). Body must be empty or {}. Repeating the call returns the same canceled resource." } }, "/wallet": { "get": { "operationId": "getWallet", "summary": "Get wallet and credits", "x-required-scope": "wallet:read", "parameters": [], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope/account restriction", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource absent or outside tenant", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Business/idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 1 MiB", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation/capability/pricing failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate limit", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retry with same key", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Required for 429; request_in_progress=1; supplied for transient 503." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Wallet" ], "description": "Money balances and, for credit accounts, the remaining SMS credits." } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "SMSGO account API key" } }, "schemas": { "TextContent": { "type": "object", "properties": { "type": { "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "type", "text" ], "additionalProperties": false }, "TemplateContent": { "type": "object", "properties": { "type": { "const": "template" }, "template_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "template_version": { "type": "integer", "minimum": 1 }, "parameters": { "type": "object", "description": "Fields/types must match the approved template version." }, "media_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "required": [ "type", "template_id" ], "additionalProperties": false }, "SendMessage": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "sms", "whatsapp", "viber" ] }, "to": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$", "examples": [ "+905321112233" ], "description": "E.164. Only Turkish mobile numbers are accepted (+90 5XX, allocated operator blocks). Refusals return 422 validation_failed with a reason in error.fields.to." }, "sender_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "Approved sender (header) ID from the panel. Optional for SMS: omit it or send null to send without a sender ID (the route's own originator is used). Required for WhatsApp." }, "content": { "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/TemplateContent" } ] }, "client_reference": { "type": "string", "minLength": 1, "maxLength": 100 }, "schedule_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "channel", "to", "content" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "channel": { "const": "sms" } } }, "then": { "properties": { "content": { "$ref": "#/components/schemas/TextContent" } } }, "else": { "properties": { "content": { "$ref": "#/components/schemas/TemplateContent" } } } } ], "description": "Time, sender, account, capability, template and tariff constraints are enforced by the server as defined in 04_API_CONTRACT.md." }, "SendBatch": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/SendMessage" }, "minItems": 1, "maxItems": 100 } }, "required": [ "messages" ], "additionalProperties": false }, "Meta": { "type": "object", "properties": { "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "request_id" ] }, "PageMeta": { "type": "object", "properties": { "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "next_cursor" ] }, "AcceptedMessage": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp", "viber" ] }, "status": { "type": "string", "enum": [ "queued", "submitting", "accepted", "unknown", "delivered", "failed", "undeliverable", "expired", "canceled" ] }, "billing_status": { "type": "string", "enum": [ "reserved", "captured", "released", "adjusted" ] }, "reserved_amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "credits": { "type": [ "integer", "null" ], "minimum": 0, "description": "SMS credits taken for this message (credit accounts only; null for wallet accounts)." } }, "required": [ "id", "channel", "status", "billing_status", "reserved_amount", "currency", "created_at", "credits" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp", "viber" ] }, "status": { "type": "string", "enum": [ "queued", "submitting", "accepted", "unknown", "delivered", "failed", "undeliverable", "expired", "canceled" ] }, "billing_status": { "type": "string", "enum": [ "reserved", "captured", "released", "adjusted" ] }, "reserved_amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "client_reference": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "schedule_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "failure_code": { "type": [ "string", "null" ], "enum": [ "send_failed", "undeliverable", "expired", null ], "description": "send_failed: could not be handed to the operator (credits/funds released). undeliverable: the operator reported it could not reach the handset. expired: the validity window ended before delivery." }, "charged_amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "credits": { "type": [ "integer", "null" ], "minimum": 0, "description": "SMS credits taken for this message (credit accounts only; null for wallet accounts)." } }, "required": [ "id", "channel", "status", "billing_status", "reserved_amount", "currency", "created_at", "client_reference", "updated_at", "schedule_at", "expires_at", "failure_code", "charged_amount", "credits" ] }, "BatchAccepted": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "const": "accepted" }, "message_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 100 }, "reserved_amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "status", "message_ids", "reserved_amount", "currency", "created_at" ] }, "BatchDetail": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "total": { "type": "integer", "minimum": 1, "maximum": 100 }, "counts_by_status": { "type": "object", "propertyNames": { "enum": [ "queued", "submitting", "accepted", "unknown", "delivered", "failed", "undeliverable", "expired", "canceled" ] }, "additionalProperties": { "type": "integer", "minimum": 0 } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "maxItems": 100 } }, "required": [ "id", "total", "counts_by_status", "messages" ] }, "Wallet": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "posted_balance": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "reserved_amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "available_balance": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,15})\\.[0-9]{8}$" }, "as_of": { "type": "string", "format": "date-time", "pattern": "Z$" }, "billing_mode": { "type": "string", "enum": [ "wallet", "credits" ], "description": "wallet: sends are paid from the money balance by tariff. credits: sends spend SMS credits." }, "credits": { "type": "integer", "minimum": 0, "description": "Remaining SMS credits (by default 1 credit per message)." } }, "required": [ "currency", "posted_balance", "reserved_amount", "available_balance", "as_of", "billing_mode", "credits" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "malformed_json", "invalid_idempotency_key", "unauthenticated", "insufficient_scope", "account_suspended", "ip_not_allowed", "resource_not_found", "method_not_allowed", "insufficient_balance", "insufficient_credits", "message_not_cancelable", "idempotency_conflict", "request_in_progress", "payload_too_large", "unsupported_media_type", "validation_failed", "invalid_cursor", "channel_unavailable", "pricing_unavailable", "rate_limited", "service_paused", "maintenance", "internal_error" ], "description": "Stable machine code; the message text is localised by Accept-Language (tr, en)." }, "message": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "error", "meta" ] }, "AcceptedResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AcceptedMessage" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "MessageResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BatchAcceptedResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BatchAccepted" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BatchResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BatchDetail" }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "ListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "WalletResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Wallet" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "type": "string", "enum": [ "message.status_changed", "message.billing_updated", "webhook.test" ] }, "schema_version": { "const": "1" }, "occurred_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "data": { "type": "object", "properties": { "message_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "queued", "submitting", "accepted", "unknown", "delivered", "failed", "undeliverable", "expired", "canceled" ] }, "billing_status": { "type": "string", "enum": [ "reserved", "captured", "released", "adjusted" ] }, "sequence": { "type": "integer", "minimum": 1 }, "client_reference": { "type": [ "string", "null" ] } }, "required": [ "message_id", "status", "billing_status", "sequence", "client_reference" ] } }, "required": [ "id", "type", "schema_version", "occurred_at", "data" ] } } }, "webhooks": { "messageEvent": { "post": { "operationId": "receiveMessageEvent", "description": "SMSGO sends to owner-configured HTTPS endpoint. HMAC SHA256 over timestamp dot raw body; replay window 300 seconds. See prose contract for retries and secret rotation. Receiver does not use an SMSGO Bearer key.", "security": [], "parameters": [ { "name": "X-SMSGO-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-SMSGO-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-SMSGO-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged" }, "default": { "description": "Failure or retry according to delivery policy" } } } } }, "tags": [ { "name": "Messages", "description": "Send, query and cancel single messages." }, { "name": "Batches", "description": "Atomic batches of up to 100 messages." }, { "name": "Wallet", "description": "Money balance and SMS credits." } ] }