{
  "openapi": "3.1.0",
  "info": {
    "title": "waboom Gateway API",
    "version": "1.0.0",
    "description": "Self-hosted WhatsApp gateway. Programmatic API, stable under /v1. Every request uses a Bearer token: an instance token for instance-scoped routes, or the ADMIN_API_KEY for instance management."
  },
  "servers": [
    { "url": "https://api.waboom.it/v1", "description": "versioned" },
    { "url": "https://api.waboom.it", "description": "unversioned alias" }
  ],
  "security": [{ "bearer": [] }],
  "components": {
    "securitySchemes": {
      "bearer": { "type": "http", "scheme": "bearer", "description": "Org API key (wbo_...) — organization-scoped, creates/operates instances headlessly; or an instance token for a single instance; or the ADMIN_API_KEY for platform admin." }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } },
      "Instance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": ["string", "null"] }, "owner": { "type": ["string", "null"] }, "state": { "type": "string" } } },
      "Status": { "type": "object", "properties": { "connection": { "type": "string", "enum": ["connecting", "qr", "open", "close"] }, "me": { "type": ["string", "null"] }, "hasCreds": { "type": "boolean" } } },
      "SendResult": { "type": "object", "properties": { "id": { "type": ["string", "null"] } } },
      "Webhook": { "type": "object", "properties": { "url": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": ["string", "null"] } } }
    }
  },
  "paths": {
    "/instances": {
      "post": { "summary": "Create instance (org API key → in its org; or admin key)", "description": "Headless bootstrap: an org API key creates an instance in its own org. Returns a per-instance token (optional to use — the org key already works on all instance routes).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "owner": { "type": "string" } } } } } }, "responses": { "201": { "description": "created; token shown once", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" } } } } } }, "401": { "description": "unauthorized" }, "403": { "description": "insufficient_role" } } },
      "get": { "summary": "List instances (org API key → its org; admin key → all)", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" } } } } } } }
    },
    "/instances/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "delete": { "summary": "Delete instance (admin key)", "responses": { "200": { "description": "ok" }, "404": { "description": "not found" } } }
    },
    "/instances/{id}/status": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": { "summary": "Connection status", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } }
    },
    "/instances/{id}/qr": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": { "summary": "Pairing QR (data URL)", "responses": { "200": { "description": "ok" }, "409": { "description": "already connected" } } }
    },
    "/instances/{id}/send/text": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Retrying with the same key replays the original response instead of resending." }],
      "post": {
        "summary": "Send a text message",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["jid", "text"], "properties": { "jid": { "type": "string" }, "text": { "type": "string" }, "quotedId": { "type": "string" } } } } } },
        "responses": { "200": { "description": "sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "429": { "description": "rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }
      }
    },
    "/instances/{id}/send/media": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "post": {
        "summary": "Send media (image/video/audio/document)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["jid", "type", "base64"], "properties": { "jid": { "type": "string" }, "type": { "type": "string", "enum": ["image", "video", "audio", "document"] }, "base64": { "type": "string" }, "caption": { "type": "string" } } } } } },
        "responses": { "200": { "description": "sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } } }
      }
    },
    "/instances/{id}/webhook": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": { "summary": "Get webhook config", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } } },
      "put": {
        "summary": "Set webhook (url + events). Deliveries are signed with HMAC-SHA256 (X-Waboom-Signature) and retried with backoff.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": ["*", "message.received", "message.status", "instance.state", "call.received"] } } } } } } },
        "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "invalid url (must be public https)" } }
      }
    }
  }
}