{
  "openapi": "3.1.0",
  "info": {
    "title": "Project Ares API Platform",
    "version": "1.0.0",
    "description": "Every frontier model behind one endpoint, one key, one bill. The model surface speaks the industry-standard Messages protocol, so existing Messages SDKs work by pointing base_url at https://api.projectares.ai.",
    "termsOfService": "https://app.projectares.ai/legal/terms",
    "contact": { "url": "https://api.projectares.ai" }
  },
  "servers": [{ "url": "https://api.projectares.ai" }],
  "security": [{ "apiKey": [] }, { "bearer": [] }],
  "paths": {
    "/v1/messages": {
      "post": {
        "operationId": "createMessage",
        "summary": "Generate a model response (optionally streaming)",
        "description": "Standard Messages request. Ares extensions: `speed: \"fast\"` (or header `x-ares-speed: fast`) requests the priority lane at 2× — billed only when actually served fast. Prompt caching via `cache_control` where supported. Deprecated models return an `x-ares-deprecation` header.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } }
        },
        "responses": {
          "200": {
            "description": "A message (JSON) or, when `stream: true`, a text/event-stream of message_start / content_block_delta / message_delta / message_stop events.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Message" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" },
          "529": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/messages/count_tokens": {
      "post": {
        "operationId": "countTokens",
        "summary": "Count input tokens without generating",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Token count (exact where the upstream tokenizer is available, estimate otherwise).",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer" } }, "required": ["input_tokens"] } } }
          },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "Every model with lifecycle metadata",
        "responses": {
          "200": {
            "description": "Active and deprecated models. Deprecated entries carry retiresAt/replacement.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }
            } } }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "Live public rate card (no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "Per-model prices in credits and USD per MTok, cache rates, the fast multiplier, and the curated brand showcase. Generated from the same table metering bills with.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Curated model catalog for pickers (no auth)",
        "security": [],
        "responses": {
          "200": { "description": "`{ models: [{ id, label, group }] }`", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/me": {
      "get": {
        "operationId": "whoAmI",
        "summary": "Introspect the calling key",
        "responses": {
          "200": { "description": "Email, plan, and available credits in micro-USD (1,000,000 = $1.00).", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Platform health (no auth)",
        "security": [],
        "responses": { "200": { "description": "`{ name, version, ok, models }`", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "sk-ares-… key from the API Platform Console" },
      "bearer": { "type": "http", "scheme": "bearer" }
    },
    "responses": {
      "Error": {
        "description": "Unified Ares error envelope. Types: invalid_request_error (400), authentication_error (401), billing_error (402), permission_error (403), not_found_error (404), rate_limit_error (429), api_error (500/502), overloaded_error (529 — retry with backoff).",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "MessageRequest": {
        "type": "object",
        "required": ["model", "max_tokens", "messages"],
        "properties": {
          "model": { "type": "string", "examples": ["claude-sonnet-5", "gpt-5.5", "zai.glm-5", "ares-mock"] },
          "max_tokens": { "type": "integer", "minimum": 1 },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InputMessage" } },
          "system": { "description": "String or array of text blocks (blocks may carry cache_control).", "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }] },
          "stream": { "type": "boolean", "default": false },
          "temperature": { "type": "number", "minimum": 0, "maximum": 1 },
          "stop_sequences": { "type": "array", "items": { "type": "string" } },
          "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } },
          "tool_choice": { "type": "object" },
          "speed": { "type": "string", "enum": ["standard", "fast"], "description": "Ares extension: \"fast\" requests the priority lane (2×; bills standard when the model can't run fast)." },
          "metadata": { "type": "object" }
        }
      },
      "InputMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["user", "assistant"] },
          "content": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object", "description": "text | image | tool_use | tool_result blocks; text blocks may carry cache_control" } }] }
        }
      },
      "Tool": {
        "type": "object",
        "required": ["name", "input_schema"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "input_schema": { "type": "object" },
          "cache_control": { "type": "object" }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "const": "message" },
          "role": { "type": "string", "const": "assistant" },
          "model": { "type": "string" },
          "content": { "type": "array", "items": { "type": "object", "description": "text or tool_use blocks" } },
          "stop_reason": { "type": "string", "enum": ["end_turn", "max_tokens", "stop_sequence", "tool_use"] },
          "stop_sequence": { "type": ["string", "null"] },
          "usage": { "$ref": "#/components/schemas/Usage" }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "input_tokens": { "type": "integer" },
          "output_tokens": { "type": "integer" },
          "cache_read_input_tokens": { "type": "integer", "description": "Billed at 10% of input" },
          "cache_creation_input_tokens": { "type": "integer", "description": "Billed at 125% of input (200% for 1-hour caches)" },
          "service_tier": { "type": "string", "description": "Present when the request ran on priority capacity" }
        }
      },
      "CountTokensRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string" },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InputMessage" } },
          "system": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }] },
          "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "const": "model" },
          "display_name": { "type": "string" },
          "family": { "type": "string", "description": "Neutral family tag (claude, gpt, open, low-latency, ares)" },
          "status": { "type": "string", "enum": ["active", "deprecated"] },
          "context_window": { "type": "integer" },
          "retiresAt": { "type": "string" },
          "replacement": { "type": "string" },
          "note": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["type", "error"],
        "properties": {
          "type": { "type": "string", "const": "error" },
          "error": {
            "type": "object",
            "required": ["type", "message"],
            "properties": {
              "type": { "type": "string", "enum": ["invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "rate_limit_error", "api_error", "overloaded_error"] },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}