{
  "openapi": "3.1.0",
  "info": {
    "title": "SuperbAPI Gateway",
    "version": "1.0.0",
    "description": "OpenAI-compatible AI gateway. One prepaid balance and one set of keys across many model families. Point any OpenAI SDK at the base URL and pass a SuperbAPI key. Independent aggregator; third-party model names are used nominatively to indicate routing.",
    "contact": { "url": "https://www.superbapi.com" }
  },
  "servers": [
    { "url": "https://www.superbapi.com/v1", "description": "OpenAI-compatible base URL" }
  ],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/models": {
      "get": {
        "summary": "List callable models",
        "description": "Returns the models the authenticated key can call, in OpenAI list format.",
        "operationId": "listModels",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "type": "string", "const": "list" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "object": { "type": "string", "const": "model" },
                          "owned_by": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" }
        }
      }
    },
    "/chat/completions": {
      "post": {
        "summary": "Create a chat completion",
        "description": "OpenAI-compatible chat completion. Usage draws down the prepaid wallet at the model's rate. Streaming is not enabled yet.",
        "operationId": "createChatCompletion",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "messages"],
                "properties": {
                  "model": { "type": "string", "examples": ["claude-opus-4-8"] },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["role", "content"],
                      "properties": {
                        "role": { "type": "string", "enum": ["system", "user", "assistant"] },
                        "content": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OpenAI-compatible completion object",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credit" }
        }
      }
    },
    "/api/v1/keys": {
      "post": {
        "summary": "Mint a scoped API key",
        "description": "Provisioning endpoint. Authenticate with a provisioning token (not a regular API key). Returns the new key value once.",
        "operationId": "provisionApiKey",
        "security": [{ "provisioningAuth": [] }],
        "servers": [{ "url": "https://www.superbapi.com" }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "allowedModels": { "type": "array", "items": { "type": "string" } },
                  "routeScope": { "type": "string" },
                  "budgetLimit": { "type": ["number", "null"] }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created key (value shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "object" },
                    "key": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List provisioned keys",
        "operationId": "listProvisionedKeys",
        "security": [{ "provisioningAuth": [] }],
        "servers": [{ "url": "https://www.superbapi.com" }],
        "responses": {
          "200": {
            "description": "Key list (values not revealed)",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } }
          }
        }
      }
    },
    "/api/v1/keys/{id}": {
      "delete": {
        "summary": "Revoke a provisioned key",
        "operationId": "revokeProvisionedKey",
        "security": [{ "provisioningAuth": [] }],
        "servers": [{ "url": "https://www.superbapi.com" }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Revoked",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your SuperbAPI key. Send as: Authorization: Bearer YOUR_API_KEY"
      },
      "provisioningAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A provisioning token (manages keys; cannot call models). Send as: Authorization: Bearer YOUR_PROVISIONING_TOKEN"
      }
    }
  }
}