{ "openapi": "3.1.0", "info": { "title": "Neopolis SMS API", "version": "2026-10-11", "description": "Messaging, media, account reads. Webhook configuration is managed in Apps & API Keys." }, "servers": [ { "url": "https://www.neopolis.net" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/messages": { "post": { "summary": "Queue SMS or MMS", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "202": { "description": "Queued; not a delivery receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accepted" } } } }, "400": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List account messages", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "before", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/validate": { "post": { "summary": "Validate without sending or reserving funds", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "200": { "description": "Validation, estimatedCharge, availableBalance, sufficientFunds, footerIncluded, testMode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Validation" } } } }, "400": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}": { "get": { "summary": "Get account message status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account": { "get": { "summary": "Balance and test restrictions", "responses": { "200": { "description": "Balance and test restrictions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/numbers": { "get": { "summary": "Active dedicated numbers", "responses": { "200": { "description": "Active dedicated numbers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Numbers" } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/media": { "post": { "summary": "Upload one JPEG/PNG/GIF", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Stored attachment id, name, contentType, url, expired, hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } } }, "400": { "description": "Media rejection", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/media/draft": { "post": { "summary": "Check MMS draft", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "text": { "type": "string" } } } } } }, "responses": { "200": { "description": "Media check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaDraft" } } } }, "400": { "description": "Media rejection", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/media/check": { "post": { "summary": "Check MMS check", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "media": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "text": { "type": "string" } } } } } }, "responses": { "200": { "description": "Media check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "maxBytes": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Media rejection", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "See errors documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/message-media/{id}": { "get": { "summary": "Download an account image", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image bytes", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Missing or expired media" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "MessageRequest": { "type": "object", "required": [ "to" ], "properties": { "from": { "type": "string", "description": "Optional owned U.S. dedicated DID; omit for automatic selection" }, "to": { "type": "string", "pattern": "^\\+1[2-9]\\d{9}$" }, "text": { "type": "string", "maxLength": 5000 }, "referenceId": { "type": "string", "maxLength": 200 }, "media": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } } }, "Accepted": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "accepted" ] }, "referenceId": { "type": [ "string", "null" ] } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": [ "string", "null" ] }, "encoding": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "referenceId": { "type": [ "string", "null" ] }, "errorCode": { "type": [ "string", "null" ] }, "segments": { "type": [ "integer", "null" ] }, "charge": { "type": [ "number", "null" ] }, "createdUtc": { "type": "string", "format": "date-time" }, "updatedUtc": { "type": "string", "format": "date-time" }, "media": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "direction": { "type": "string", "enum": [ "IN", "OUT" ] } } }, "Validation": { "type": "object", "properties": { "valid": { "type": "boolean" }, "sent": { "type": "boolean", "const": false }, "from": { "type": "string" }, "to": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "MMS" ] }, "segments": { "type": "integer" }, "encoding": { "type": "string" }, "estimatedCharge": { "type": "number" }, "availableBalance": { "type": "number" }, "sufficientFunds": { "type": "boolean" }, "footerIncluded": { "type": "boolean" }, "testMode": { "type": "boolean" } } }, "Account": { "type": "object", "properties": { "balance": { "type": "number" }, "tenDlcApproved": { "type": "boolean" }, "testMode": { "type": "boolean" }, "testDestination": { "type": [ "string", "null" ] } } }, "Number": { "type": "object", "properties": { "number": { "type": "string" }, "monthlyFee": { "type": "number" } } }, "Numbers": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/Number" } } } }, "Media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif" ] }, "url": { "type": "string" }, "expired": { "type": "boolean" }, "hash": { "type": "string" } } }, "MediaDraft": { "type": "object", "properties": { "withinLimit": { "type": "boolean" }, "error": { "type": "string" }, "maxBytes": { "type": "integer", "format": "int64" }, "estimatedBytes": { "type": "integer", "format": "int64" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "apiVersion": { "type": "string", "const": "2026-10-11" }, "type": { "type": "string", "enum": [ "message.received", "message.status", "webhook.test" ] }, "occurredUtc": { "type": "string", "format": "date-time" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "properties": { "message": { "type": "string" } } } ] } } } } }, "webhooks": { "messageEvent": { "post": { "summary": "Neopolis posts a signed message event to the URL configured for your app", "security": [], "parameters": [ { "name": "Neopolis-Event-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Neopolis-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Neopolis-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1= followed by lowercase HMAC-SHA256(timestamp + dot + exact raw body), using literal whsec_ secret" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "responses": { "200": { "description": "Event durably accepted; duplicates acknowledged" }, "401": { "description": "Signature verification failed" }, "503": { "description": "Not accepted; Neopolis retries" } } } } } }