{
  "openapi": "3.1.0",
  "info": {
    "title": "Maksa API",
    "version": "1.0.0-preview",
    "summary": "OpenAI-compatible batch inference on the cheapest unsold GPU hours on earth, on a deadline, with a receipt.",
    "description": "Sample specification describing the future public API. Endpoints mirror the OpenAI Files and Batches APIs with one addition: every job carries a deadline. This document is static; the marketing site does not call it.",
    "contact": { "name": "Maksa", "email": "hello@maksa.com", "url": "https://maksa.com/docs" }
  },
  "servers": [{ "url": "https://api.maksa.com/v1", "description": "Production (preview)" }],
  "security": [{ "bearer": [] }],
  "tags": [
    { "name": "Prices", "description": "The public GPU price index. No key required." },
    { "name": "Quotes", "description": "Price a job before you run it." },
    { "name": "Jobs", "description": "Submit and track batch jobs (OpenAI Batches compatible)." },
    { "name": "Receipts", "description": "One per finished job, verifiable offline." },
    { "name": "Account", "description": "Balance, residency, exit." }
  ],
  "paths": {
    "/prices": {
      "get": {
        "tags": ["Prices"], "operationId": "getPrices", "summary": "Current GPU-hour prices by provider and region", "security": [],
        "parameters": [
          { "name": "gpu", "in": "query", "schema": { "type": "string", "enum": ["H100", "B200"] } },
          { "name": "region", "in": "query", "schema": { "type": "string" }, "description": "Region id, e.g. is-cap-kef" }
        ],
        "responses": { "200": { "description": "Snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesSnapshot" } } } } }
      }
    },
    "/prices/history": {
      "get": {
        "tags": ["Prices"], "operationId": "getPricesHistory", "summary": "Daily min / median / max for the last 90 days", "security": [],
        "parameters": [{ "name": "gpu", "in": "query", "required": true, "schema": { "type": "string", "enum": ["H100", "B200"] } }],
        "responses": { "200": { "description": "History", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesHistory" } } } } }
      }
    },
    "/quotes": {
      "post": {
        "tags": ["Quotes"], "operationId": "createQuote", "summary": "Price a job: where it would run, when it would finish, what it costs",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInput" } } } },
        "responses": { "200": { "description": "Quote, or a counter-offer when the deadline is infeasible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } } }
      }
    },
    "/files": {
      "post": {
        "tags": ["Jobs"], "operationId": "uploadFile", "summary": "Upload a JSONL input file (OpenAI-compatible)",
        "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": ["batch"] } }, "required": ["file", "purpose"] } } } },
        "responses": { "200": { "description": "File object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } }
      }
    },
    "/batches": {
      "post": {
        "tags": ["Jobs"], "operationId": "createBatch", "summary": "Submit a job with a deadline",
        "description": "Identical to OpenAI's Batches API, plus `deadline`. `completion_window` is accepted and ignored when `deadline` is present.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInput" } } } },
        "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } }
      },
      "get": {
        "tags": ["Jobs"], "operationId": "listBatches", "summary": "List jobs",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Page of batches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" } }, "has_more": { "type": "boolean" } } } } } } }
      }
    },
    "/batches/{id}": {
      "get": {
        "tags": ["Jobs"], "operationId": "getBatch", "summary": "Job status, placement and ETA",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } }
      }
    },
    "/batches/{id}/cancel": {
      "post": {
        "tags": ["Jobs"], "operationId": "cancelBatch", "summary": "Cancel; you pay only for GPU-hours already used",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } }
      }
    },
    "/receipts/{id}": {
      "get": {
        "tags": ["Receipts"], "operationId": "getReceipt", "summary": "The receipt for a finished job", "security": [],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "mk-hssvj-nk" } }],
        "responses": { "200": { "description": "Receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "404": { "description": "No such receipt" } }
      }
    },
    "/account/exit": {
      "post": {
        "tags": ["Account"], "operationId": "exitAccount", "summary": "Export everything, refund the balance, close the account",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["export_to"], "properties": { "export_to": { "type": "string", "example": "s3://your-bucket/maksa" }, "refund_balance": { "type": "boolean", "default": true } } } } } },
        "responses": { "202": { "description": "Exit scheduled", "content": { "application/json": { "schema": { "type": "object", "properties": { "exit_id": { "type": "string" }, "refund_usd": { "type": "number" }, "refund_by": { "type": "string", "format": "date" } } } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Keys start with mk_live_ or mk_test_." } },
    "schemas": {
      "Gpu": { "type": "string", "enum": ["H100", "B200"] },
      "Tier": { "type": "string", "enum": ["1h", "6h", "24h", "72h"] },
      "PriceRow": {
        "type": "object", "required": ["provider", "region", "gpu", "on_demand", "interruptible", "our_24h"],
        "properties": {
          "provider": { "type": "string" }, "provider_id": { "type": "string" }, "region": { "type": "string" }, "region_id": { "type": "string" },
          "gpu": { "$ref": "#/components/schemas/Gpu" },
          "on_demand": { "type": "number", "description": "USD per GPU-hour" },
          "interruptible": { "type": "number", "description": "USD per GPU-hour" },
          "our_24h": { "type": "number", "description": "Maksa price for a 24h-deadline job in this region, USD per GPU-hour" }
        }
      },
      "PricesSnapshot": {
        "type": "object", "required": ["generated_at", "rows", "cheapest_now"],
        "properties": {
          "generated_at": { "type": "string", "format": "date-time" },
          "rows": { "type": "array", "items": { "$ref": "#/components/schemas/PriceRow" } },
          "cheapest_now": { "type": "object", "properties": { "region_id": { "type": "string" }, "name": { "type": "string" }, "gpu": { "$ref": "#/components/schemas/Gpu" }, "price": { "type": "number" } } }
        }
      },
      "PricesHistory": {
        "type": "object",
        "properties": {
          "generated_at": { "type": "string", "format": "date-time" }, "gpu": { "$ref": "#/components/schemas/Gpu" },
          "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "min": { "type": "number" }, "median": { "type": "number" }, "max": { "type": "number" } } } }
        }
      },
      "QuoteInput": {
        "type": "object", "required": ["model", "tokens", "deadline"],
        "properties": { "model": { "type": "string", "example": "llama-3.3-70b" }, "tokens": { "type": "integer", "example": 50000000 }, "deadline": { "$ref": "#/components/schemas/Tier" } }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "generated_at": { "type": "string", "format": "date-time" }, "feasible": { "type": "boolean" },
          "price": { "type": "number" }, "per_million": { "type": "number" },
          "gpu": { "$ref": "#/components/schemas/Gpu" }, "gpu_hours": { "type": "number" }, "gpus": { "type": "integer" },
          "placements": { "type": "array", "items": { "type": "object", "properties": { "region_id": { "type": "string" }, "share": { "type": "number" }, "price": { "type": "number" } } } },
          "start_at": { "type": "string", "format": "date-time" }, "finish_at": { "type": "string", "format": "date-time" }, "deadline_at": { "type": "string", "format": "date-time" },
          "comparisons": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "region": { "type": "string" }, "rate": { "type": "number" }, "cost": { "type": "number" } } } },
          "saving_pct": { "type": "number" },
          "counter_offer": { "type": "object", "properties": { "reason": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "deadline": { "$ref": "#/components/schemas/Tier" }, "price": { "type": "number" }, "finish_at": { "type": "string", "format": "date-time" } } } } } }
        }
      },
      "File": { "type": "object", "properties": { "id": { "type": "string" }, "bytes": { "type": "integer" }, "purpose": { "type": "string" }, "created_at": { "type": "integer" } } },
      "BatchInput": {
        "type": "object", "required": ["input_file_id", "endpoint", "deadline"],
        "properties": {
          "input_file_id": { "type": "string" },
          "endpoint": { "type": "string", "enum": ["/v1/chat/completions", "/v1/completions", "/v1/embeddings"] },
          "deadline": { "$ref": "#/components/schemas/Tier" },
          "model": { "type": "string" },
          "output_bucket": { "type": "string", "example": "s3://your-bucket/maksa" },
          "regions": { "type": "array", "items": { "type": "string" }, "description": "Residency constraint: region ids or jurisdictions (us, eu, apac)" },
          "metadata": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "Batch": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }, "object": { "type": "string", "const": "batch" },
          "status": { "type": "string", "enum": ["validating", "queued", "in_progress", "delivering", "completed", "failed", "cancelled"] },
          "deadline": { "$ref": "#/components/schemas/Tier" }, "deadline_at": { "type": "string", "format": "date-time" },
          "placement": { "type": "array", "items": { "type": "object", "properties": { "region_id": { "type": "string" }, "gpu": { "$ref": "#/components/schemas/Gpu" }, "gpus": { "type": "integer" } } } },
          "eta": { "type": "string", "format": "date-time" },
          "receipt_id": { "type": ["string", "null"] }
        }
      },
      "Receipt": {
        "type": "object",
        "description": "Fields are hashed individually (sha-256 over `maksa:receipt:v1:<key>=<value>`, first 12 hex); the digests joined by ':' in canonical order hash to `hash`.",
        "required": ["id", "customer", "model", "tokens", "tier", "submitted_at", "deadline_at", "delivered_at", "region", "gpu", "gpu_hours", "cost", "would_have_cost", "saving", "deletion_at", "field_digests", "hash", "generated_at"],
        "properties": {
          "id": { "type": "string" }, "customer": { "type": "string", "description": "Stable redacted name, e.g. otter-7" },
          "model": { "type": "string" }, "tokens": { "type": "integer", "description": "Rounded to three significant figures" },
          "tier": { "$ref": "#/components/schemas/Tier" },
          "submitted_at": { "type": "string", "format": "date-time" }, "deadline_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": "string", "format": "date-time" },
          "region": { "type": "string" }, "gpu": { "$ref": "#/components/schemas/Gpu" }, "gpu_hours": { "type": "number" },
          "cost": { "type": "number" }, "would_have_cost": { "type": "number" }, "saving": { "type": "number" },
          "deletion_at": { "type": "string", "format": "date-time" },
          "field_digests": { "type": "object", "additionalProperties": { "type": "string" } },
          "hash": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}