# CrossCompute API Parameter Registry

This document lists the full external parameter surface for CrossCompute APIs.

Base URL:

- `https://www.crosscompute.io`

Auth header conventions:

- Agent API calls: `Authorization: Bearer cc_agent_...`
- Human dashboard API calls: `Authorization: Bearer <supabase_access_token>`
- Inference API calls: `Authorization: Bearer cc_live_...` or `cc_agent_...`

Content type conventions:

- JSON requests: `Content-Type: application/json`
- Markdown response (`/api/agents/skill-md`): `text/markdown`

## 1) Agent APIs

### `POST /api/agents/register`

Headers:

- `Content-Type: application/json` (required)
- `x-agent-registration-secret` (required only when server enables `AGENT_REGISTRATION_SECRET`)

JSON body:

- `agentId` string, required  
  rule: `/^[A-Za-z0-9._:-]{3,128}$/`
- `name` string, optional, max 120 chars
- `skillMdUrl` string, optional, max 1000 chars, should be `http(s)` URL

Response:

- `201` first creation with `apiKey`
- `200` existing account/key (`apiKey: null`)
- fields: `created`, `account`, `key`, `apiKey`

### `GET /api/agents/me`

Headers:

- `Authorization: Bearer cc_agent_...` (required)

Response fields:

- `account.id`
- `account.agentId`
- `account.name`
- `account.skillMdUrl`
- `account.creditsPurchased`
- `key.id`
- `key.label`
- `key.prefix`
- `key.quotaCredits`
- `key.usedCredits`
- `key.remainingCredits`
- `key.active`

### `GET /api/agents/usage`

Headers:

- `Authorization: Bearer cc_agent_...` (required)

Response fields:

- `agentId`
- `keyPrefix`
- `quotaCredits`
- `usedCredits`
- `remainingCredits`
- `creditsPurchased`

### `GET /api/agents/usage-models`

Headers:

- `Authorization: Bearer cc_agent_...` (required)

Response fields:

- `items[]` with:
  - `provider`
  - `model`
  - `inputTokens`
  - `outputTokens`
  - `totalTokens`
  - `requestCount`
  - `lastRequestAt`
  - `updatedAt`

### `GET /api/agents/skill-md`

Headers:

- `Authorization: Bearer cc_agent_...` (required)

Response:

- `200` markdown text
- `404` if no stored `skill_md_content`

### `POST /api/agents/topup`

Headers:

- `Authorization: Bearer cc_agent_...` (required)
- `Content-Type: application/json`
- one payment header for paid retry:
  - `payment-signature` (x402 standard)
  - or `x-payment`

Body:

- `{}` (no business fields required)

x402 response headers (debug/diagnostics):

- `x-crosscompute-payment-header-present`: `true|false`
- `x-crosscompute-payment-header-kind`: `payment-signature|x-payment|none`

Response:

- `402` payment challenge when payment is required
- `200` settled topup with:
  - `topup.creditsAdded`
  - `topup.usdAmount`
  - `topup.txHash`
  - `topup.channel`
  - `account` summary
  - `key` summary

## 2) Inference APIs

### `GET /v1/models`

Headers:

- `Authorization: Bearer cc_live_...|cc_agent_...` (required)

Response:

- OpenAI-style list object:
  - `object: "list"`
  - `data[]` model objects:
    - `id`
    - `object: "model"`
    - `created`
    - `owned_by`
    - `permission`

Response headers:

- `x-crosscompute-model-catalog: local`
- `x-crosscompute-model-count: <number>`

### `GET /v1/models/{model_id}`

Path parameters:

- `model_id` string (required, URL-encoded when needed)

Headers:

- `Authorization: Bearer cc_live_...|cc_agent_...` (required)

Response:

- `200` model object
- `404` with `code: model_not_found`

### `POST /v1/chat/completions`

Headers:

- `Authorization: Bearer cc_live_...|cc_agent_...` (required)
- `Content-Type: application/json`

Required JSON fields:

- `model` string
- `messages` array

`model` accepted values:

- routing profiles: `auto`, `cheap`, `medium`, `premium`
- legacy aliases: `eco`, `balanced`, `blockrun/<profile>`
- explicit model IDs (examples):
  - `deepseek-chat`
  - `openai/gpt-5-mini`
  - `anthropic/claude-sonnet-4.6`
  - `qwen/qwen-plus`
  - `google/gemini-2.5-flash`

Supported optional JSON fields:

- `stream` boolean
- `max_tokens` number
- `max_completion_tokens` number
- `temperature` number
- `top_p` number
- `tools` array (OpenAI function-tool format)
- `tool_choice` string or object
- `response_format` object
- `parallel_tool_calls` boolean
- `metadata` object
- `user` string

Message roles accepted:

- `system`, `developer`, `user`, `assistant`, `tool`

Message content accepted:

- plain string
- OpenAI content-part arrays with part types:
  - `text`
  - `input_text`
  - `image_url`
  - `input_image`

Compatibility notes:

- `developer` is normalized to `system` when required by downstream adapter.
- `max_completion_tokens` is normalized to provider-specific token fields.
- Anthropic adapter maps OpenAI tool format to Anthropic `tool_use`/`tool_result`.

Observability response headers:

- `x-crosscompute-routing-profile`
- `x-crosscompute-routing-tier`
- `x-crosscompute-routing-budget`
- `x-crosscompute-routing-version`
- `x-crosscompute-routing-reason`
- `x-crosscompute-routing-intelligence` (`notdiamond|local`)
- `x-crosscompute-routing-intelligence-session`
- `x-crosscompute-routing-intelligence-request-id`
- `x-crosscompute-routing-attempts`
- `x-crosscompute-requested-model`
- `x-crosscompute-routed-model`
- `x-crosscompute-upstream-model`
- `x-crosscompute-provider`
- `x-crosscompute-adapter`
- `x-crosscompute-stream-downgraded`
- `x-crosscompute-billing-mode`
- `x-crosscompute-billed-credits`
- `x-crosscompute-billed-credits-base`
- `x-crosscompute-billed-fee-credits`
- `x-crosscompute-billed-fee-rate`
- `x-crosscompute-billed-usd`
- `x-crosscompute-price-rule`
- `x-crosscompute-price-source`
- `x-crosscompute-usage-model`
- `x-crosscompute-input-tokens`
- `x-crosscompute-output-tokens`
- `x-crosscompute-total-tokens`
- compression headers (when compression applies):
  - `x-crosscompute-compression`
  - `x-crosscompute-compression-ratio`
  - `x-crosscompute-compression-original-chars`
  - `x-crosscompute-compression-final-chars`

Important:

- `x-crosscompute-routing-profile` is a response header, not a request parameter.
- To request cheap routing, set request body `model` to `"cheap"`.
- For explicit models (for example `openai/gpt-4o`), CrossCompute now enforces strict routing: if that model is not available on configured providers, request returns `400` instead of silently falling back.

## 3) Human Account APIs

### `POST /api/bootstrap-account`

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)

Body:

- none required

Response:

- `ok`
- `autoCreatedApiKey` (present on first bootstrap only)

### `GET /api/keys`

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)

Response:

- `keys[]` with id/label/prefix/quota/usage/active timestamps

### `POST /api/keys`

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)
- `Content-Type: application/json`

JSON body:

- `label` string, optional (max 60 chars)
- `quotaCredits` number, required, must be `> 0`

Response:

- `apiKey` (shown once)
- `key` summary

### `POST /api/keys/{id}/deactivate`

Path parameters:

- `id` UUID string (required)

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)

Response:

- `ok: true`

### `GET /api/usage-models`

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)

Response:

- `items[]` with provider/model token rollups

### `GET /api/dashboard/analytics`

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)

Query parameters:

- `days` integer, optional, default `30`, range `[1, 365]`
- `limit` integer, optional, default `300`, range `[20, 2000]`

Response:

- `summary`
- `payments[]`
- `creditEvents[]`
- `timeline[]`
- `modelUsage[]`
- `source.usageEventsAvailable`

### `GET /api/payments/stripe/options`

No auth required.

Response:

- `stripe.enabled`
- `stripe.runtimeLoaded`
- `stripe.configured`
- `stripe.publishableKey`
- `stripe.currency`
- `stripe.creditPacks[]`

### `POST /api/payments/stripe/checkout-session`

Headers:

- `Authorization: Bearer <supabase_access_token>` (required)

JSON body:

- `packId` string, optional (preset top-up pack)
- `usdAmount` number, optional (custom top-up amount in USD)
- `keyId` UUID string, optional (target API key to receive credits)

Notes:

- At least one of `packId` or `usdAmount` is required.
- If `usdAmount` is used, credits are calculated from server-side `CREDIT_USD_VALUE`.

Response:

- `sessionId`
- `checkoutUrl`
- `pack`
- `key`

### `POST /api/payments/stripe/webhook`

No user auth. Stripe webhook signature verification required.

Headers:

- `stripe-signature` (required)

## 4) System APIs

### `GET /health`

No auth required.

Response includes:

- `ok`
- `supabaseConfigured`
- `paymentChannels`
- `providersConfigured`

### `GET /api/config`

No auth required.

Response:

- `supabaseUrl`
- `supabaseAnonKey`
- `stripe`
- `freeCreditsOnSignup`

### `GET /api/compatibility`

No auth required.

Response:

- `proxy`
- `routing`
- `endpoints`
- `providerAdapters`

### `GET /api/me`

Optional auth.

Headers:

- `Authorization: Bearer <supabase_access_token>` (optional)

Response:

- `authenticated`
- `user` (or `null`)

## 5) Operator Environment Parameters

All runtime environment parameters are listed in:

- project file `.env.example`
- server loader `src/config/env.js`

Key groups:

- Core runtime: `PORT`, `HOST`, `NODE_ENV`
- Supabase: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`
- Account defaults: `DEFAULT_NEW_USER_KEY_*`, `DEFAULT_NEW_AGENT_KEY_*`, `AGENT_REGISTRATION_SECRET`
- Billing: `DEFAULT_REQUEST_CREDITS`, `BILLING_DECIMAL_PLACES`, `BILLING_FEE_RATE`, `CREDIT_USD_VALUE`
- Routing/compression: `PROXY_ROUTING_*`, `PROXY_COMPRESSION_*`, `PROXY_BODY_LIMIT`
- Providers: `DEEPSEEK_*`, `OPENAI_*`, `ANTHROPIC_*`, `QWEN_*`, `KIMI_*`, `GEMINI_*`, `GROK_*`, `MINIMAX_*`, `LLAMA_*`, `TOGETHER_*`
- Pricing override: `MODEL_PRICING_OVERRIDES_JSON`
- x402: `X402_*` (network/payto/facilitator/auth/topup)
- Stripe (optional): `STRIPE_*`