{ "openapi": "3.1.0", "info": { "title": "SMS Gateway API", "version": "1.0.0", "description": "A single SMS API for all projects. The SMS provider behind it can change at any time without any change on the client side." }, "servers": [ { "url": "https://sms.befoundonline.ps/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "SMS", "description": "Send messages" }, { "name": "Messages", "description": "Track your own messages" }, { "name": "Account", "description": "Token check and statistics" }, { "name": "Health", "description": "Availability checks" } ], "paths": { "/sms/send": { "post": { "tags": [ "SMS" ], "summary": "Send an SMS now", "description": "Sends within the request and returns the final result. Requires the `sms.send` ability.", "operationId": "sendSms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsRequest" } } } }, "responses": { "200": { "description": "SMS sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "SMS sent successfully" ] }, "data": { "$ref": "#/components/schemas/SmsMessage" } } } } } }, "201": { "$ref": "#/components/responses/Unauthenticated" }, "202": { "$ref": "#/components/responses/Forbidden" }, "203": { "$ref": "#/components/responses/ValidationError" }, "204": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/DeliveryFailed" }, "503": { "$ref": "#/components/responses/DeliveryFailed" }, "504": { "$ref": "#/components/responses/DeliveryFailed" } } } }, "/sms/send-async": { "post": { "tags": [ "SMS" ], "summary": "Queue an SMS", "description": "Stores the message and sends it from the queue with automatic retries. Poll `GET /sms/{id}` for the outcome. Requires the `sms.send` ability.", "operationId": "queueSms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsRequest" } } } }, "responses": { "202": { "description": "SMS queued for delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "SMS queued for delivery" ] }, "data": { "$ref": "#/components/schemas/SmsMessage" } } } } } }, "203": { "$ref": "#/components/responses/Unauthenticated" }, "204": { "$ref": "#/components/responses/Forbidden" }, "205": { "$ref": "#/components/responses/ValidationError" }, "206": { "$ref": "#/components/responses/RateLimited" } } } }, "/sms/send-bulk": { "post": { "tags": [ "SMS" ], "summary": "Queue the same SMS for many recipients", "description": "Always queued. Duplicate numbers are sent once. Requires the `sms.bulk` ability.", "operationId": "sendBulkSms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBulkSmsRequest" } } } }, "responses": { "202": { "description": "Bulk SMS queued for delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "Bulk SMS queued for delivery" ] }, "data": { "$ref": "#/components/schemas/BulkResult" } } } } } }, "203": { "$ref": "#/components/responses/Unauthenticated" }, "204": { "$ref": "#/components/responses/Forbidden" }, "205": { "$ref": "#/components/responses/ValidationError" }, "206": { "$ref": "#/components/responses/RateLimited" } } } }, "/sms": { "get": { "tags": [ "Messages" ], "summary": "List your messages", "description": "Newest first. Requires the `messages.read` ability.", "operationId": "listSms", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "queued", "sent", "delivered", "failed" ] } }, { "name": "batch_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Messages retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "Messages retrieved" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMessage" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/sms/{id}": { "get": { "tags": [ "Messages" ], "summary": "Get one of your messages", "operationId": "getSms", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "Message retrieved" ] }, "data": { "$ref": "#/components/schemas/SmsMessage" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sms/batches/{batch_id}": { "get": { "tags": [ "Messages" ], "summary": "Get the progress of a bulk batch", "operationId": "getBatch", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "Batch retrieved" ] }, "data": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "total": { "type": "integer" }, "pending": { "type": "integer" }, "queued": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/stats": { "get": { "tags": [ "Account" ], "summary": "Your sending statistics", "description": "Requires the `stats.read` ability.", "operationId": "getStats", "responses": { "200": { "description": "Statistics retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "Statistics retrieved" ] }, "data": { "$ref": "#/components/schemas/Statistics" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/me": { "get": { "tags": [ "Account" ], "summary": "Check your token and limits", "operationId": "getCurrentClient", "responses": { "200": { "description": "Authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "examples": [ "Authenticated" ] }, "data": { "$ref": "#/components/schemas/Client" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Gateway health (no authentication)", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "example": { "success": true, "status": "ok", "checks": { "database": "ok" }, "timestamp": "2026-01-01T10:00:00+00:00" } } } }, "503": { "description": "Degraded" } } } }, "/provider-health": { "get": { "tags": [ "Health" ], "summary": "Whether the SMS provider is reachable", "description": "Cached for a short time. The provider itself is never named.", "operationId": "getProviderHealth", "responses": { "200": { "description": "Reachable", "content": { "application/json": { "example": { "success": true, "status": "ok", "latency_ms": 182, "checked_at": "2026-01-01T10:00:00+00:00" } } } }, "503": { "description": "Unavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The API token issued for your project." } }, "schemas": { "SendSmsRequest": { "type": "object", "required": [ "to", "message" ], "properties": { "to": { "type": "string", "description": "Local (0591234567) or international (+970591234567 / 00970591234567) format.", "examples": [ "0591234567" ] }, "message": { "type": "string", "maxLength": 1000, "examples": [ "Your verification code is 123456" ] } } }, "SendBulkSmsRequest": { "type": "object", "required": [ "recipients", "message" ], "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "description": "Local (0591234567) or international (+970591234567 / 00970591234567) format.", "examples": [ "0591234567" ] } }, "message": { "type": "string", "maxLength": 1000 } } }, "SmsMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Gateway message id. Use it with GET /sms/{id}." }, "message_id": { "type": [ "string", "null" ], "description": "Message id assigned by the SMS provider, once sent." }, "status": { "type": "string", "enum": [ "pending", "queued", "sent", "delivered", "failed" ] }, "to": { "type": "string", "examples": [ "+970591234567" ] }, "segments": { "type": "integer", "description": "Number of SMS parts billed." }, "encoding": { "type": "string", "enum": [ "gsm7", "ucs2" ] }, "batch_id": { "type": [ "string", "null" ], "format": "uuid" }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "FORBIDDEN", "HTTPS_REQUIRED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "VALIDATION_ERROR", "HTTP_ERROR", "SMS_RATE_LIMITED", "SMS_QUOTA_EXCEEDED", "SMS_INVALID_NUMBER", "SMS_PROVIDER_ERROR", "SMS_AUTHENTICATION_ERROR", "SMS_PROVIDER_UNAVAILABLE", "SMS_TIMEOUT", "SMS_UNKNOWN_ERROR" ] }, "message": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BulkResult": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "total": { "type": "integer" }, "duplicates_removed": { "type": "integer" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMessage" } } } }, "Statistics": { "type": "object", "properties": { "total": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "today": { "type": "integer" }, "this_month": { "type": "integer" }, "segments": { "type": "integer" } } }, "Client": { "type": "object", "properties": { "name": { "type": "string" }, "abilities": { "type": "array", "items": { "type": "string" } }, "rate_limit_per_minute": { "type": "integer" }, "daily_quota": { "type": [ "integer", "null" ] }, "messages_today": { "type": "integer" } } }, "Error": { "type": "object", "required": [ "success", "message", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "FORBIDDEN", "HTTPS_REQUIRED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "VALIDATION_ERROR", "HTTP_ERROR", "SMS_RATE_LIMITED", "SMS_QUOTA_EXCEEDED", "SMS_INVALID_NUMBER", "SMS_PROVIDER_ERROR", "SMS_AUTHENTICATION_ERROR", "SMS_PROVIDER_UNAVAILABLE", "SMS_TIMEOUT", "SMS_UNKNOWN_ERROR" ] }, "errors": { "type": "object", "description": "Validation errors per field (VALIDATION_ERROR only)." }, "retry_after": { "type": "integer", "description": "Seconds to wait (429 only)." }, "reference": { "type": "string", "format": "uuid", "description": "Gateway message id of a failed send." } } } } } }, "responses": { "Unauthenticated": { "description": "Missing, invalid, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Invalid or missing API token.", "error": { "code": "UNAUTHENTICATED" } } } } }, "Forbidden": { "description": "The client lacks the ability required by the endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "This API client is not allowed to use this endpoint (requires the \"sms.bulk\" ability).", "error": { "code": "FORBIDDEN" } } } } }, "NotFound": { "description": "Not found, or owned by another client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "The requested resource was not found.", "error": { "code": "NOT_FOUND" } } } } }, "ValidationError": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "The to field is required.", "error": { "code": "VALIDATION_ERROR", "errors": { "to": [ "The to field is required." ] } } } } } }, "RateLimited": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Rate limit exceeded. Retry after 42 seconds.", "error": { "code": "SMS_RATE_LIMITED", "retry_after": 42 } } } } }, "DeliveryFailed": { "description": "The provider did not accept the message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Unable to send SMS", "error": { "code": "SMS_PROVIDER_ERROR", "description": "The SMS provider rejected the message.", "reference": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" } } } } } } } }