{
  "openapi": "3.0.3",
  "info": { "title": "Creda Connect SMS API", "version": "1.0.0", "description": "Send SMS to Ghanaian numbers using your Creda credits and approved sender IDs. Sandbox keys (cr_sandbox_) simulate; live keys (cr_live_) send real SMS. Limit: 30 requests per minute per account." },
  "servers": [{ "url": "https://creda.credit/api/public" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } },
      "SendRequest": {
        "type": "object",
        "required": ["sender", "recipients", "message", "permission"],
        "properties": {
          "sender": { "type": "string", "example": "MyShop" },
          "recipients": { "type": "array", "items": { "type": "string" }, "example": ["0241234567"] },
          "message": { "type": "string", "example": "Hello {{name}}, your order is ready." },
          "names": { "type": "object", "additionalProperties": { "type": "string" } },
          "fallback": { "type": "string", "example": "Customer" },
          "permission": { "type": "boolean", "description": "Confirms recipients agreed to receive messages.", "example": true }
        }
      }
    },
    "responses": {
      "Unauthorized": { "description": "Invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/v1/sms/send": {
      "post": {
        "summary": "Send SMS",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" } } } },
        "responses": { "200": { "description": "Accepted or simulated" }, "400": { "description": "Invalid request" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Sender not approved" }, "409": { "description": "Idempotency key reused with different payload" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/credits/balance": { "get": { "summary": "Get credit balance", "responses": { "200": { "description": "Balance" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } },
    "/v1/senders": { "get": { "summary": "List approved sender IDs", "responses": { "200": { "description": "Senders" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } },
    "/v1/messages": {
      "get": {
        "summary": "List messages",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": { "200": { "description": "Messages" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/v1/messages/{id}": {
      "get": {
        "summary": "Get a message",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Message" }, "404": { "description": "Not found" } }
      }
    }
  }
}