{
  "openapi": "3.0.3",
  "info": {
    "title": "Smart Services API",
    "version": "1.0.0",
    "description": "Smart Services unified API for MaaS (Models as a Service) and more.\n\nAuthentication:\n- Prefer: `Authorization: Bearer <APP_KEY>`\n- Also supported: `x-api-key: <APP_KEY>`\n\nBase URL: `https://your-smart-services.com` (or your deployment origin)"
  },
  "servers": [
    { "url": "https://your-smart-services.com" },
    { "url": "http://localhost:3000" }
  ],
  "tags": [
    { "name": "maas", "description": "Models as a Service (chat, models)" },
    { "name": "pricing", "description": "AI model pricing data (public, no auth for list endpoints)" },
    { "name": "storage", "description": "File storage upload/download/describe/delete" },
    { "name": "search", "description": "Full-text search collections and documents" },
    { "name": "vector", "description": "Vector DB collections, points, and search" },
    { "name": "email", "description": "Transactional email with tracking, sender management, and campaign analytics" },
    { "name": "jobs", "description": "Background jobs (enqueue and cron schedules)" },
    { "name": "chat", "description": "Real-time messaging with conversations, participants, and messages" }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" },
      "BearerAuth": { "type": "http", "scheme": "bearer" }
    },
    "schemas": {
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["system", "user", "assistant"] },
          "content": { "type": "string" }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string", "description": "Model id, e.g. openai:gpt-4o-mini" },
          "stream": { "type": "boolean", "default": false },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "enum": ["chat.completion"] },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": {
                  "type": "object",
                  "properties": {
                    "role": { "type": "string" },
                    "content": { "type": "string" }
                  }
                },
                "finish_reason": { "type": "string" }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "provider": { "type": "string" },
              "usage": {
                "type": "object",
                "properties": {
                  "prompt_tokens": { "type": "integer" },
                  "completion_tokens": { "type": "integer" },
                  "total_tokens": { "type": "integer" }
                }
              },
              "cost": { "nullable": true }
            }
          }
        }
      },
      "ModelItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "openai:gpt-4o-mini" },
          "object": { "type": "string", "example": "model" },
          "created": { "type": "integer" },
          "owned_by": { "type": "string" }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "list" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelItem" } }
        }
      },
      "EmailSendRequest": {
        "type": "object",
        "required": ["to", "subject"],
        "properties": {
          "to": { "type": "array", "items": { "type": "string" }, "description": "Recipient email addresses" },
          "subject": { "type": "string", "description": "Email subject" },
          "text": { "type": "string", "description": "Plain text body" },
          "html": { "type": "string", "description": "HTML body" },
          "toName": { "type": "string", "description": "Recipient display name" },
          "fromName": { "type": "string", "description": "Sender display name" },
          "replyTo": { "type": "string", "description": "Reply-to email address" },
          "senderId": { "type": "string", "description": "Sender account ID to use" },
          "trackingEnabled": { "type": "boolean", "description": "Enable open/click tracking", "default": false },
          "campaign": { "type": "string", "description": "Campaign identifier" },
          "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization" },
          "metadata": { "type": "object", "description": "Custom metadata (JSON)" }
        }
      },
      "EmailSender": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string", "description": "Internal name" },
          "email": { "type": "string", "description": "Sender email address" },
          "fromName": { "type": "string", "description": "Display name" },
          "replyTo": { "type": "string", "description": "Reply-to address" },
          "smtpHost": { "type": "string", "description": "Custom SMTP host" },
          "smtpPort": { "type": "integer", "description": "Custom SMTP port" },
          "smtpSecure": { "type": "boolean", "description": "Use TLS/SSL" },
          "smtpUser": { "type": "string", "description": "SMTP username" },
          "isDefault": { "type": "boolean", "description": "Is default sender" },
          "isActive": { "type": "boolean", "description": "Is active" },
          "totalSent": { "type": "integer" },
          "totalDelivered": { "type": "integer" },
          "totalOpened": { "type": "integer" },
          "totalClicked": { "type": "integer" },
          "totalBounced": { "type": "integer" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "EmailLog": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "to": { "type": "array", "items": { "type": "string" } },
          "from": { "type": "string" },
          "subject": { "type": "string" },
          "senderId": { "type": "string" },
          "campaign": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "trackingId": { "type": "string" },
          "status": { "type": "string", "enum": ["sent", "delivered", "opened", "clicked", "failed"] },
          "sentAt": { "type": "string", "format": "date-time" },
          "openedAt": { "type": "string", "format": "date-time" },
          "openCount": { "type": "integer" },
          "firstClickedAt": { "type": "string", "format": "date-time" },
          "clickCount": { "type": "integer" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "CampaignStats": {
        "type": "object",
        "properties": {
          "campaign": { "type": "string" },
          "totalSent": { "type": "integer" },
          "totalDelivered": { "type": "integer" },
          "totalOpened": { "type": "integer" },
          "totalClicked": { "type": "integer" },
          "totalFailed": { "type": "integer" },
          "totalUnsubscribed": { "type": "integer" },
          "openRate": { "type": "number", "description": "Percentage" },
          "clickRate": { "type": "number", "description": "Percentage" },
          "firstSentAt": { "type": "string", "format": "date-time" },
          "lastSentAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  },
  "security": [
    { "BearerAuth": [] },
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/api/v1/maas/models": {
      "get": {
        "tags": ["maas"],
        "summary": "List available models",
        "description": "Returns the list of enabled model IDs available to your app.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -H \"x-api-key: $APP_KEY\" \n  \"$BASE_URL/api/v1/maas/models\"" },
          { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch(BASE_URL + '/api/v1/maas/models', { headers: { 'x-api-key': APP_KEY } });\nconst models = await res.json();" },
          { "lang": "python", "label": "Python", "source": "import requests\nresp = requests.get(f\"{BASE_URL}/api/v1/maas/models\", headers={'x-api-key': APP_KEY})\nmodels = resp.json()" }
        ]
      }
    },
    "/api/v1/maas/chat/completions": {
      "post": {
        "tags": ["maas"],
        "summary": "Create a chat completion",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } },
              "text/event-stream": { "schema": { "type": "string", "description": "SSE stream when stream=true" } }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \n  -H \"x-api-key: $APP_KEY\" \n  -H \"Content-Type: application/json\" \n  -d '{\n    \"model\": \"openai:gpt-4o-mini\",\n    \"stream\": false,\n    \"messages\": [{\"role\":\"user\",\"content\":\"hello world\"}]\n  }' \n  \"$BASE_URL/api/v1/maas/chat/completions\"" },
          { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch(BASE_URL + '/api/v1/maas/chat/completions', {\n  method: 'POST',\n  headers: { 'x-api-key': APP_KEY, 'Content-Type': 'application/json' },\n  body: JSON.stringify({ model: 'openai:gpt-4o-mini', stream: false, messages: [{ role: 'user', content: 'hello world' }] })\n});\nconst chat = await res.json();" },
          { "lang": "python", "label": "Python", "source": "import requests, json\nheaders = { 'x-api-key': APP_KEY, 'Content-Type': 'application/json' }\npayload = { 'model': 'openai:gpt-4o-mini', 'stream': False, 'messages': [ { 'role': 'user', 'content': 'hello world' } ] }\nresp = requests.post(f\"{BASE_URL}/api/v1/maas/chat/completions\", headers=headers, data=json.dumps(payload))\nchat = resp.json()" }
        ]
      }
    },
    "/api/v1/storage": {
      "put": {
        "tags": ["storage"],
        "summary": "Upload a file (multipart form-data)",
        "description": "Upload a file as multipart/form-data. Fields: `file` (required), `key` (optional, defaults to the filename), `contentType` (optional), `catalog` (optional). Optional image optimization: send an `optimisations` field (JSON, e.g. `{\"width\":800,\"quality\":80}` — `{}` accepts defaults) and any image is converted to WebP server-side. The original is NOT stored — only the optimized WebP is kept, and the stored key gains a `.webp` extension. The response includes `optimized: true` when this happened.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "key": { "type": "string", "description": "Storage key/filename. Defaults to the uploaded filename." },
                  "contentType": { "type": "string" },
                  "catalog": { "type": "string", "description": "Optional organizational grouping key." },
                  "optimisations": { "type": "string", "description": "JSON: { width?: number (default 800), quality?: number 1-100 (default 80) }. When present and the file is an image, it is converted to WebP and the original is discarded." }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl — Upload", "source": "curl -X PUT \"$BASE_URL/api/v1/storage\" \\\n  -H \"x-api-key: $APP_KEY\" \\\n  -F \"file=@./my-file.txt\" \\\n  -F \"key=my-file.txt\"" },
          { "lang": "bash", "label": "Curl — Image → WebP", "source": "# Converts the image to WebP and discards the original\ncurl -X PUT \"$BASE_URL/api/v1/storage\" \\\n  -H \"x-api-key: $APP_KEY\" \\\n  -F \"file=@./photo.png\" \\\n  -F \"key=photo.png\" \\\n  -F 'optimisations={\"width\":1200,\"quality\":82}'" },
          { "lang": "javascript", "label": "JavaScript", "source": "const form = new FormData();\nform.set('file', fileBlob, 'photo.png');\nform.set('key', 'photo.png');\n// Optional: convert images to WebP (original discarded). Omit for raw storage.\nform.set('optimisations', JSON.stringify({ width: 1200, quality: 82 }));\nconst res = await fetch(BASE_URL + '/api/v1/storage', { method: 'PUT', headers: { 'x-api-key': APP_KEY }, body: form });\nconst json = await res.json(); // json.optimized === true when converted" },
          { "lang": "python", "label": "Python", "source": "import requests, json\nfiles = { 'file': ('photo.png', open('photo.png','rb')) }\n# Optional: convert images to WebP (original discarded)\ndata = { 'key': 'photo.png', 'optimisations': json.dumps({'width':1200,'quality':82}) }\nr = requests.put(f\"{BASE_URL}/api/v1/storage\", headers={'x-api-key': APP_KEY}, files=files, data=data)\nprint(r.json())" }
        ]
      },
      "get": {
        "tags": ["storage"],
        "summary": "Download a file",
        "parameters": [ { "in": "query", "name": "uploadId", "schema": { "type": "string" }, "required": true } ],
        "responses": { "200": { "description": "OK", "content": { "application/octet-stream": {} } } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl — Download", "source": "curl -H \"x-api-key: $APP_KEY\" \n  \"$BASE_URL/api/v1/storage?uploadId=$UPLOAD_ID\" > my-file.txt" }
        ]
      },
      "post": {
        "tags": ["storage"],
        "summary": "Describe file metadata",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl — Describe", "source": "curl -X POST \"$BASE_URL/api/v1/storage\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"uploadId\":\"$UPLOAD_ID\"}'" }
        ]
      },
      "delete": {
        "tags": ["storage"],
        "summary": "Delete a file",
        "parameters": [ { "in": "query", "name": "uploadId", "schema": { "type": "string" }, "required": true } ],
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl — Delete", "source": "curl -X DELETE \"$BASE_URL/api/v1/storage?uploadId=$UPLOAD_ID\" \\\n  -H \"x-api-key: $APP_KEY\"" }
        ]
      }
    }
    ,
    "/api/v1/search/collections/create": {
      "post": {
        "tags": ["search"],
        "summary": "Create a search collection",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/search/collections/create\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"articles\",\n  \"fields\": [ {\"name\":\"id\",\"type\":\"string\"}, {\"name\":\"title\",\"type\":\"string\"}, {\"name\":\"body\",\"type\":\"string\"} ]\n}'" }
        ]
      }
    },
    "/api/v1/search/documents/upsert": {
      "post": {
        "tags": ["search"],
        "summary": "Upsert documents",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/search/documents/upsert\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"collection\": \"articles\",\n  \"docs\": [ {\"id\":\"1\", \"payload\": {\"title\":\"Hello\", \"body\":\"World\"} } ]\n}'" }
        ]
      }
    },
    "/api/v1/search/query": {
      "post": {
        "tags": ["search"],
        "summary": "Query search index",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/search/query\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"collection\": \"articles\",\n  \"q\": \"hello\",\n  \"queryBy\": \"title,body\"\n}'" }
        ]
      }
    },
    "/api/v1/search/collections/delete": {
      "post": {
        "tags": ["search"],
        "summary": "Delete a search collection",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/search/collections/delete\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"articles\"}'" }
        ]
      }
    },
    "/api/v1/vector/collections/create": {
      "post": {
        "tags": ["vector"],
        "summary": "Create vector collection",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/vector/collections/create\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"embeddings\",\n  \"vectorSize\": 3,\n  \"distance\": \"Cosine\"\n}'" }
        ]
      }
    },
    "/api/v1/vector/points/upsert": {
      "post": {
        "tags": ["vector"],
        "summary": "Upsert points",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/vector/points/upsert\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"collection\": \"embeddings\",\n  \"points\": [ {\"id\":\"p1\",\"vector\":[0.1,0.2,0.3],\"payload\":{\"label\":\"A\"}} ]\n}'" }
        ]
      }
    },
    "/api/v1/vector/search": {
      "post": {
        "tags": ["vector"],
        "summary": "Vector search",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/vector/search\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"collection\": \"embeddings\",\n  \"vector\": [0.1,0.2,0.3],\n  \"limit\": 3\n}'" }
        ]
      }
    },
    "/api/v1/vector/points/delete": {
      "post": {
        "tags": ["vector"],
        "summary": "Delete points",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/vector/points/delete\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"collection\":\"embeddings\",\"ids\":[\"p1\"]}'" }
        ]
      }
    },
    "/api/v1/vector/collections/delete": {
      "post": {
        "tags": ["vector"],
        "summary": "Delete vector collection",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl ", "source": "curl -X POST \"$BASE_URL/api/v1/vector/collections/delete\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"embeddings\"}'" }
        ]
      }
    }
  ,
    "/api/v1/email/send": {
      "post": {
        "tags": ["email"],
        "summary": "Send transactional email",
        "description": "Send an email with optional tracking, campaigns, and sender selection",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmailSendRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "emailId": { "type": "string" },
                    "messageId": { "type": "string" }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \"$BASE_URL/api/v1/email/send\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"to\": [\"user@example.com\"],\n  \"subject\": \"Welcome!\",\n  \"html\": \"<h1>Welcome to our platform</h1>\",\n  \"trackingEnabled\": true,\n  \"campaign\": \"onboarding\"\n}'" },
          { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(BASE_URL + '/api/v1/email/send', {\n  method: 'POST',\n  headers: { 'x-api-key': APP_KEY, 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    to: ['user@example.com'],\n    subject: 'Welcome!',\n    html: '<h1>Welcome to our platform</h1>',\n    trackingEnabled: true,\n    campaign: 'onboarding'\n  })\n});\nconst data = await response.json();" },
          { "lang": "python", "label": "Python", "source": "import requests\nresponse = requests.post(\n  f\"{BASE_URL}/api/v1/email/send\",\n  headers={'x-api-key': APP_KEY, 'Content-Type': 'application/json'},\n  json={\n    'to': ['user@example.com'],\n    'subject': 'Welcome!',\n    'html': '<h1>Welcome to our platform</h1>',\n    'trackingEnabled': True,\n    'campaign': 'onboarding'\n  }\n)\ndata = response.json()" }
        ]
      }
    },
    "/api/v1/email/senders": {
      "get": {
        "tags": ["email"],
        "summary": "List sender accounts",
        "description": "Get all sender accounts for your app",
        "responses": {
          "200": {
            "description": "List of senders",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/EmailSender" }
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl \"$BASE_URL/api/v1/email/senders\" \\\n  -H \"x-api-key: $APP_KEY\"" }
        ]
      },
      "post": {
        "tags": ["email"],
        "summary": "Create sender account",
        "description": "Create a new sender account with optional custom SMTP",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "fromName"],
                "properties": {
                  "name": { "type": "string", "description": "Internal name" },
                  "email": { "type": "string", "description": "Sender email" },
                  "fromName": { "type": "string", "description": "Display name" },
                  "replyTo": { "type": "string" },
                  "smtpHost": { "type": "string" },
                  "smtpPort": { "type": "integer" },
                  "smtpSecure": { "type": "boolean" },
                  "smtpUser": { "type": "string" },
                  "smtpPass": { "type": "string" },
                  "isDefault": { "type": "boolean" },
                  "isActive": { "type": "boolean", "default": true }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sender created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/EmailSender" }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \"$BASE_URL/api/v1/email/senders\" \\\n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Support Team\",\n  \"email\": \"support@example.com\",\n  \"fromName\": \"Example Support\",\n  \"isDefault\": true\n}'" }
        ]
      }
    },
    "/api/v1/email/senders/{id}": {
      "get": {
        "tags": ["email"],
        "summary": "Get sender account",
        "parameters": [
          { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Sender details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/EmailSender" }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["email"],
        "summary": "Update sender account",
        "parameters": [
          { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string" },
                  "fromName": { "type": "string" },
                  "replyTo": { "type": "string" },
                  "isDefault": { "type": "boolean" },
                  "isActive": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Sender updated" }
        }
      },
      "delete": {
        "tags": ["email"],
        "summary": "Delete sender account",
        "parameters": [
          { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Sender deleted" }
        }
      }
    },
    "/api/v1/email/senders/{id}/set-default": {
      "post": {
        "tags": ["email"],
        "summary": "Set sender as default",
        "parameters": [
          { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Default sender updated" }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \"$BASE_URL/api/v1/email/senders/sender_abc123/set-default\" \\\n  -H \"x-api-key: $APP_KEY\"" }
        ]
      }
    },
    "/api/v1/email/logs": {
      "get": {
        "tags": ["email"],
        "summary": "List and filter email logs",
        "description": "Get email logs with filtering and pagination",
        "parameters": [
          { "in": "query", "name": "campaign", "schema": { "type": "string" }, "description": "Filter by campaign" },
          { "in": "query", "name": "senderId", "schema": { "type": "string" }, "description": "Filter by sender ID" },
          { "in": "query", "name": "status", "schema": { "type": "string", "enum": ["sent", "delivered", "opened", "clicked", "failed"] }, "description": "Filter by status" },
          { "in": "query", "name": "to", "schema": { "type": "string" }, "description": "Filter by recipient email" },
          { "in": "query", "name": "startDate", "schema": { "type": "string", "format": "date-time" }, "description": "Filter emails after this date" },
          { "in": "query", "name": "endDate", "schema": { "type": "string", "format": "date-time" }, "description": "Filter emails before this date" },
          { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Results per page" },
          { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" }
        ],
        "responses": {
          "200": {
            "description": "Email logs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/EmailLog" }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "offset": { "type": "integer" },
                        "hasMore": { "type": "boolean" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl \"$BASE_URL/api/v1/email/logs?campaign=onboarding&limit=20\" \\\n  -H \"x-api-key: $APP_KEY\"" },
          { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n  BASE_URL + '/api/v1/email/logs?campaign=onboarding&limit=20',\n  { headers: { 'x-api-key': APP_KEY } }\n);\nconst data = await response.json();" },
          { "lang": "python", "label": "Python", "source": "import requests\nresponse = requests.get(\n  f\"{BASE_URL}/api/v1/email/logs\",\n  headers={'x-api-key': APP_KEY},\n  params={'campaign': 'onboarding', 'limit': 20}\n)\ndata = response.json()" }
        ]
      }
    },
    "/api/v1/email/tracking/{emailId}": {
      "get": {
        "tags": ["email"],
        "summary": "Get email tracking details",
        "description": "Get detailed tracking information for a specific email including all events",
        "parameters": [
          { "in": "path", "name": "emailId", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Email tracking details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "email": { "$ref": "#/components/schemas/EmailLog" },
                        "events": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": { "type": "string" },
                              "eventType": { "type": "string", "enum": ["opened", "clicked", "bounced", "unsubscribed"] },
                              "clickedUrl": { "type": "string" },
                              "ipAddress": { "type": "string" },
                              "userAgent": { "type": "string" },
                              "createdAt": { "type": "string", "format": "date-time" }
                            }
                          }
                        },
                        "sender": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string" },
                            "name": { "type": "string" },
                            "email": { "type": "string" },
                            "fromName": { "type": "string" }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "sent": { "type": "boolean" },
                            "opened": { "type": "boolean" },
                            "clicked": { "type": "boolean" },
                            "openCount": { "type": "integer" },
                            "clickCount": { "type": "integer" },
                            "eventCount": { "type": "integer" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl \"$BASE_URL/api/v1/email/tracking/email_abc123\" \\\n  -H \"x-api-key: $APP_KEY\"" },
          { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n  BASE_URL + '/api/v1/email/tracking/email_abc123',\n  { headers: { 'x-api-key': APP_KEY } }\n);\nconst data = await response.json();" }
        ]
      }
    },
    "/api/v1/email/campaigns": {
      "get": {
        "tags": ["email"],
        "summary": "Get campaign statistics",
        "description": "Get aggregated statistics for all campaigns",
        "responses": {
          "200": {
            "description": "Campaign statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CampaignStats" }
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "totalCampaigns": { "type": "integer" },
                        "totalEmailsSent": { "type": "integer" },
                        "totalOpened": { "type": "integer" },
                        "totalClicked": { "type": "integer" },
                        "totalUnsubscribed": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl \"$BASE_URL/api/v1/email/campaigns\" \\\n  -H \"x-api-key: $APP_KEY\"" },
          { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n  BASE_URL + '/api/v1/email/campaigns',\n  { headers: { 'x-api-key': APP_KEY } }\n);\nconst data = await response.json();" },
          { "lang": "python", "label": "Python", "source": "import requests\nresponse = requests.get(\n  f\"{BASE_URL}/api/v1/email/campaigns\",\n  headers={'x-api-key': APP_KEY}\n)\ndata = response.json()" }
        ]
      }
    },
    "/api/v1/jobs/enqueue": {
      "post": {
        "tags": ["jobs"],
        "summary": "Enqueue one-off job",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "201": { "description": "Created" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \n  -d '{\n  \"delayMs\": 10000, \"target\": { \"url\": \"https://example.com/webhook\", \"method\": \"POST\", \"headers\": { \"Content-Type\": \"application/json\" }, \"body\": { \"hello\": \"world\" } }\n}' \n  \"$BASE_URL/api/v1/jobs/enqueue\"" }
        ]
      }
    },
    "/api/v1/jobs/cron.create": {
      "post": {
        "tags": ["jobs"],
        "summary": "Create cron schedule",
        "requestBody": { "required": true, "content": { "application/json": {} } },
        "responses": { "201": { "description": "Created" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \n  -H \"x-api-key: $APP_KEY\" -H \"Content-Type: application/json\" \n  -d '{\n  \"name\": \"hourly-ping\", \"cron\": \"0 * * * *\", \"timezone\": \"UTC\",\n  \"target\": { \"url\": \"https://example.com/webhook\", \"method\": \"POST\" }\n}' \n  \"$BASE_URL/api/v1/jobs/cron.create\"" }
        ]
      }
    },
    "/api/v1/jobs/cron.list": {
      "get": {
        "tags": ["jobs"],
        "summary": "List cron schedules",
        "responses": { "200": { "description": "OK" } },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -H \"x-api-key: $APP_KEY\" \n  \"$BASE_URL/api/v1/jobs/cron.list\"" }
        ]
      }
    },
    "/api/v1/chat/regenerate-key": {
      "post": {
        "tags": ["chat"],
        "summary": "Regenerate chat widget key",
        "description": "Regenerate the chat widget key for your app. The old key will be immediately invalidated. Requires regular API key authentication (not chat key).",
        "responses": {
          "200": {
            "description": "Chat key regenerated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "chatKey": { "type": "string", "example": "chat_abc123..." },
                    "message": { "type": "string", "example": "Chat key regenerated successfully" }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Chat service not enabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string", "example": "Chat service is not enabled for this app" }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \"$BASE_URL/api/v1/chat/regenerate-key\" \\\n  -H \"x-api-key: $APP_KEY\"" },
          { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch(BASE_URL + '/api/v1/chat/regenerate-key', {\n  method: 'POST',\n  headers: { 'x-api-key': APP_KEY }\n});\nconst data = await res.json();\nconsole.log('New chat key:', data.chatKey);" },
          { "lang": "python", "label": "Python", "source": "import requests\nheaders = { 'x-api-key': APP_KEY }\nresp = requests.post(f\"{BASE_URL}/api/v1/chat/regenerate-key\", headers=headers)\ndata = resp.json()\nprint('New chat key:', data['chatKey'])" }
        ]
      }
    },
    "/api/v1/pricing/providers": {
      "get": {
        "tags": ["pricing"],
        "summary": "List providers with pricing data",
        "description": "Public endpoint (no auth required). Returns providers that have pricing data along with model counts and last sync times.",
        "responses": {
          "200": {
            "description": "List of providers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "providers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "provider": { "type": "string" },
                          "name": { "type": "string" },
                          "modelCount": { "type": "integer" },
                          "pricingPageUrl": { "type": "string", "nullable": true },
                          "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true },
                          "syncMethod": { "type": "string", "nullable": true }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl \"$BASE_URL/api/v1/pricing/providers\"" }
        ]
      }
    },
    "/api/v1/pricing/models": {
      "get": {
        "tags": ["pricing"],
        "summary": "List model pricing",
        "description": "Public endpoint (no auth required). Returns pricing data for all models, optionally filtered by provider or category.",
        "parameters": [
          { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Filter by provider (openai, anthropic, google)" },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["text", "image", "embedding", "audio", "video"] }, "description": "Filter by category" }
        ],
        "responses": {
          "200": {
            "description": "List of model pricing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "count": { "type": "integer" },
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "provider": { "type": "string" },
                          "modelId": { "type": "string" },
                          "modelName": { "type": "string" },
                          "category": { "type": "string" },
                          "inputPer1M": { "type": "number", "nullable": true },
                          "outputPer1M": { "type": "number", "nullable": true },
                          "imagePer1": { "type": "number", "nullable": true },
                          "currency": { "type": "string" },
                          "notes": { "type": "string", "nullable": true },
                          "updatedAt": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "providerSyncInfo": { "type": "object" }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl \"$BASE_URL/api/v1/pricing/models?provider=openai\"" }
        ]
      }
    },
    "/api/v1/pricing/lookup": {
      "post": {
        "tags": ["pricing"],
        "summary": "Look up specific model pricing (rate-limited)",
        "description": "Rate-limited endpoint to look up pricing for specific models. Requires a public API key (get one from POST /api/public/keys).",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["models"],
                "properties": {
                  "models": {
                    "type": "array",
                    "description": "Array of model IDs (strings) or objects with provider and modelId",
                    "items": {
                      "oneOf": [
                        { "type": "string" },
                        { "type": "object", "properties": { "provider": { "type": "string" }, "modelId": { "type": "string" } } }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lookup results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "models": { "type": "array", "items": { "type": "object" } },
                    "notFound": { "type": "array", "items": { "type": "string" } },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "used": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "remaining": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" },
          "429": { "description": "Rate limit exceeded" }
        },
        "x-codeSamples": [
          { "lang": "bash", "label": "Curl", "source": "curl -X POST \"$BASE_URL/api/v1/pricing/lookup\" \\\n  -H \"x-api-key: pk_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"models\": [\"gpt-4o\", \"claude-3-5-sonnet\"]}'" }
        ]
      }
    }
  }
}