{
  "openapi": "3.1.0",
  "info": {
    "title": "Verxl Inference API",
    "version": "1.0.0",
    "description": "OpenAI-compatible inference clearing. Route a request, receive the completion and see the 50 bps protocol fee and provider payout. Documentation, model discovery and health are public; every inference call requires a funded Verxl API key.",
    "contact": {
      "name": "Verxl",
      "url": "https://verxl.com/docs"
    },
    "x-verxl-qwen-output-floor": 256
  },
  "servers": [
    {
      "url": "https://api.verxl.com",
      "description": "Dedicated API host"
    },
    {
      "url": "https://verxl.com",
      "description": "Apex host"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List models and prices",
        "description": "Public. No authentication required. Returns the OpenAI-compatible model list plus Verxl clearing and documentation metadata.",
        "security": [],
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create an inference completion",
        "description": "OpenAI Chat Completions compatible. Requires `Authorization: Bearer vrxl_live_...` and a funded balance. Set `stream: true` for SSE.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              },
              "examples": {
                "deepseek": {
                  "summary": "Paid DeepSeek request",
                  "value": {
                    "model": "deepseek-v4.1-flash",
                    "messages": [
                      {
                        "role": "user",
                        "content": "Draft a short Rust client."
                      }
                    ],
                    "max_tokens": 512,
                    "stream": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion or SSE stream",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                },
                "example": {
                  "id": "chatcmpl_01JVERXL",
                  "object": "chat.completion",
                  "created": 1762000000,
                  "model": "qwen3.5-4b-uncensored-64k",
                  "choices": [
                    {
                      "index": 0,
                      "message": {
                        "role": "assistant",
                        "content": "The protocol takes 50 bps, so the provider keeps 99.5% of the compute charge."
                      },
                      "finish_reason": "stop"
                    }
                  ],
                  "usage": {
                    "prompt_tokens": 24,
                    "completion_tokens": 23,
                    "total_tokens": 47
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "OpenAI-style SSE chunks ending in data: [DONE]"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Edge and protocol health",
        "description": "Public. No authentication required.",
        "security": [],
        "responses": {
          "200": {
            "description": "Health telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "vrxl_live_...",
        "description": "Verxl API key created and funded at https://verxl.com/console. Required for every inference request."
      }
    },
    "schemas": {
      "Model": {
        "type": "object",
        "required": [
          "id",
          "object",
          "owned_by"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "qwen3.5-4b-uncensored-64k"
            ]
          },
          "object": {
            "type": "string",
            "const": "model"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          },
          "context_window": {
            "type": "integer"
          },
          "context_display": {
            "type": "string"
          },
          "tier": {
            "type": "string"
          },
          "is_official_bridge": {
            "type": "boolean"
          },
          "pricing": {
            "type": "object",
            "properties": {
              "prompt_usd_per_1m": {
                "type": "number"
              },
              "cached_prompt_usd_per_1m": {
                "type": "number"
              },
              "completion_usd_per_1m": {
                "type": "number"
              },
              "protocol_fee_bps": {
                "type": "integer"
              }
            }
          },
          "context_length": {
            "type": "integer"
          },
          "max_model_len": {
            "type": "integer"
          }
        }
      },
      "ModelList": {
        "type": "object",
        "required": [
          "object",
          "data"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          },
          "verxl_clearing": {
            "type": "object",
            "additionalProperties": true
          },
          "verxl_docs": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "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",
            "enum": [
              "qwen3.5-4b-uncensored-64k",
              "deepseek-v4.1-flash",
              "mimo-v2.6-flash"
            ]
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "default": 0.7
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "maximum": 32768,
            "default": 8192,
            "description": "Default 8192, capped at 32768. Qwen 3.5 4B is floored at 256 effective output tokens to avoid an empty reasoning-only response.",
            "x-verxl-min-output-tokens": {
              "qwen3.5-4b-uncensored-64k": 256
            }
          },
          "stream": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "ChatResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "choices",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": "string"
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "message",
              "type"
            ],
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "param": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid JSON or missing messages",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid Authorization header or bad API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "The API key has no funded balance, or the selected model is not covered by the account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Demo rate limit reached",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Upstream or routing failure",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}