{
  "openapi": "3.0.3",
  "info": {
    "title": "CrossCompute API",
    "version": "1.2.0",
    "description": "Unified API surface for human dashboard workflows and autonomous agent workflows, including OpenAI-compatible inference and x402 credit top-ups. Full parameter registry: https://www.crosscompute.io/api-parameters.md"
  },
  "servers": [
    {
      "url": "https://www.crosscompute.io"
    }
  ],
  "tags": [
    {
      "name": "System"
    },
    {
      "name": "Users"
    },
    {
      "name": "Agents"
    },
    {
      "name": "Inference"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health and capability flags",
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/config": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Public frontend config",
        "responses": {
          "200": {
            "description": "Public Supabase values used by the web app"
          }
        }
      }
    },
    "/api/me": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get current signed-in user",
        "security": [
          {
            "SupabaseAccessToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current user status"
          },
          "401": {
            "description": "Missing or invalid access token"
          }
        }
      }
    },
    "/api/bootstrap-account": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Create user profile and first API key",
        "security": [
          {
            "SupabaseAccessToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Bootstrap completed"
          }
        }
      }
    },
    "/api/keys": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "List user API keys",
        "security": [
          {
            "SupabaseAccessToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "API key list"
          }
        }
      },
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Create a user API key",
        "security": [
          {
            "SupabaseAccessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "example": "Production"
                  },
                  "quotaCredits": {
                    "type": "number",
                    "example": 1000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key created"
          }
        }
      }
    },
    "/api/keys/{id}/deactivate": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Deactivate user API key",
        "security": [
          {
            "SupabaseAccessToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Key deactivated"
          }
        }
      }
    },
    "/api/agents/register": {
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Register or update an agent account",
        "description": "Creates agent account and returns cc_agent key on first creation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRegisterRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent account created or updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRegisterResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/agents/me": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Get current agent account",
        "security": [
          {
            "BearerApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Agent profile"
          },
          "401": {
            "description": "Invalid agent key"
          }
        }
      }
    },
    "/api/agents/usage": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Get agent credit usage",
        "security": [
          {
            "BearerApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Usage snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentUsageResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/agents/topup": {
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Top up credits using x402",
        "description": "If unpaid, this endpoint can respond with HTTP 402 payment challenge.",
        "security": [
          {
            "BearerApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Top-up success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentTopupResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required"
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "tags": [
          "Inference"
        ],
        "summary": "List local CrossCompute model catalog",
        "description": "Returns an OpenAI-style model list generated by CrossCompute from configured providers plus routing profiles (`auto`, `cheap`, `medium`, `premium`).",
        "security": [
          {
            "BearerApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Model list",
            "headers": {
              "x-crosscompute-model-catalog": {
                "description": "Catalog source (`local`).",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-model-count": {
                "description": "Number of models in response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models/{model_id}": {
      "get": {
        "tags": [
          "Inference"
        ],
        "summary": "Get one model entry from local catalog",
        "security": [
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "model_id",
            "in": "path",
            "required": true,
            "description": "Model id from `/v1/models` list. URL-encode special characters when needed.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Model entry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelObject"
                }
              }
            }
          },
          "404": {
            "description": "Model not found"
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "Inference"
        ],
        "summary": "OpenAI-compatible chat completions",
        "description": "Use model as a routing profile (`auto`, `cheap`, `medium`, `premium`) or explicit model ID (for example `openai/gpt-5-mini`, `anthropic/claude-sonnet-4-6`, `deepseek-chat`). Request normalization supports `developer` role and OpenAI content parts (`input_text`, `input_image`) for improved client compatibility.",
        "security": [
          {
            "BearerApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upstream model response",
            "headers": {
              "x-crosscompute-routing-profile": {
                "description": "Resolved routing profile (`explicit` for explicit model calls).",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routing-tier": {
                "description": "Complexity tier selected by router (`SIMPLE`, `MEDIUM`, `COMPLEX`, `REASONING`) when profile routing is used.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routing-budget": {
                "description": "Resolved budget profile (`cheap`, `medium`, `premium`) when profile routing is used.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routing-version": {
                "description": "Router engine version.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routing-intelligence": {
                "description": "Routing intelligence engine (`notdiamond` or `local`).",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routing-intelligence-session": {
                "description": "NotDiamond routing session id when available.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routing-intelligence-request-id": {
                "description": "NotDiamond request id when available.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-routed-model": {
                "description": "Final model selected for the upstream call.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-provider": {
                "description": "Final provider selected for the upstream call.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-price-rule": {
                "description": "Pricing rule id applied for billing.",
                "schema": {
                  "type": "string"
                }
              },
              "x-crosscompute-billed-credits": {
                "description": "Credits charged for this request.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "402": {
            "description": "Quota exceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "CrossCompute API Key"
      },
      "SupabaseAccessToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Supabase Access Token"
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "supabaseConfigured": {
            "type": "boolean"
          },
          "x402": {
            "type": "object"
          },
          "providersConfigured": {
            "type": "object"
          }
        }
      },
      "AgentRegisterRequest": {
        "type": "object",
        "required": [
          "agentId"
        ],
        "properties": {
          "agentId": {
            "type": "string",
            "example": "ops-agent-001"
          },
          "name": {
            "type": "string",
            "example": "Ops Agent"
          },
          "skillMdUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/skill.md"
          }
        }
      },
      "AgentRegisterResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "account": {
            "type": "object"
          },
          "key": {
            "type": "object"
          },
          "apiKey": {
            "type": "string",
            "description": "Present on first key creation"
          }
        }
      },
      "AgentUsageResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "usage": {
            "type": "object"
          }
        }
      },
      "AgentTopupResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "topup": {
            "type": "object"
          },
          "account": {
            "type": "object"
          },
          "key": {
            "type": "object"
          }
        }
      },
      "ModelObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "example": "model"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          },
          "permission": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "id",
          "object"
        ]
      },
      "ModelListResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelObject"
            }
          }
        }
      },
      "ChatCompletionsRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Routing profile or explicit model id. Profiles: `auto`, `cheap`, `medium`, `premium` (legacy aliases `eco`, `balanced` also accepted). Explicit examples: `openai/gpt-5-mini`, `anthropic/claude-sonnet-4-6`, `deepseek-chat`.",
            "example": "auto"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": {
                  "type": "string",
                  "description": "OpenAI-compatible role. `developer` is accepted and normalized to `system`.",
                  "example": "user"
                },
                "content": {
                  "oneOf": [
                    {
                      "type": "string",
                      "example": "Hello"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "example": "input_text"
                          },
                          "text": {
                            "type": "string",
                            "example": "Hello"
                          },
                          "image_url": {
                            "oneOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "object"
                              }
                            ]
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "max_completion_tokens": {
            "type": "integer",
            "description": "Accepted for OpenAI clients. CrossCompute normalizes to provider-specific token fields when required."
          },
          "max_tokens": {
            "type": "integer",
            "description": "Legacy OpenAI field. CrossCompute normalizes this for providers that require different token parameter names."
          },
          "temperature": {
            "type": "number"
          },
          "top_p": {
            "type": "number"
          },
          "tools": {
            "type": "array",
            "description": "OpenAI function tool schema.",
            "items": {
              "type": "object"
            }
          },
          "tool_choice": {
            "description": "OpenAI tool choice (`auto`, `none`, `required`, or function selector object).",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ]
          },
          "response_format": {
            "type": "object"
          },
          "parallel_tool_calls": {
            "type": "boolean"
          },
          "metadata": {
            "type": "object"
          },
          "user": {
            "type": "string"
          },
          "stream": {
            "type": "boolean",
            "default": false
          }
        }
      }
    }
  }
}