# LiquidCompute API Docs

Base URL: https://api.liquidcompute.co

This documentation describes the LiquidCompute API for authenticated GPU
price index data, current vendor-price data, and the customer RFQ workspace.

## Key Pages

- Interactive API docs: /
- OpenAPI specification: /openapi.yaml
- RFQ and machine access reference: /rfq
- RFQ customer and guest specification: /rfq.openapi.yaml

## Endpoint Groups

- Health: GET /health
- Custom Index (intraday, per-GPU, key-scoped; index_ids such as h100-us,
  h200-us, b200-us, b300-us, a100-us — your key's grant is authoritative,
  see GET /v1/custom-index/reference; history at resolution 30m or 1h, or
  with resolution omitted, also requires the intraday entitlement, while
  resolution=1d needs only the index): GET /v1/custom-index/available,
  GET /v1/custom-index/current, GET /v1/custom-index/as-of,
  GET /v1/custom-index/history, GET /v1/custom-index/reference
- Transaction Index (daily; gpu_family hopper|blackwell or gpu_group h100,
  mutually exclusive; index_type raw|blended_sigmoid — blended_static was
  retired):
  GET /v1/txn-index/current, GET /v1/txn-index/as-of, GET /v1/txn-index/history
- Informational Index (daily EWMA, extended history):
  GET /v1/info-index/available, GET /v1/info-index/current,
  GET /v1/info-index/as-of, GET /v1/info-index/history
- Private Transactions (per-deal records, included with Enterprise; full dataset
  in one response; gpu_model, contract_type, region, start, end filters;
  requires the private-txns entitlement):
  GET /v1/private-transactions
- GPU Market Prices (current vendor-published offers normalized to USD per
  GPU-hour from the newest completed scrape; no query parameters; requires
  the gpu-prices entitlement; 503 data_unavailable with Retry-After until the
  first scrape completes): GET /v1/gpu-prices/current
- GPU Price History and Change Log (per-offer daily step series over a UTC
  date window of at most 92 days, gpu_model + start + end; price_changed,
  listed and delisted events since a date, gpu_model + since; requires the
  gpu-prices entitlement): GET /v1/gpu-prices/history,
  GET /v1/gpu-prices/changes
- Status (last successful update and next expected update for the custom
  index, GPU prices and reference series; any valid key):
  GET /v1/status/freshness
- Inference (OpenAI-compatible chat completions on open-weights models served
  by Liquid Compute GPU nodes; point an OpenAI SDK at
  https://api.liquidcompute.co/v1; stream: true returns server-sent events
  ending in data: [DONE]; the model list carries context limits and prices,
  and the OpenRouter provider feed carries the same catalogue; each key may
  have a tier-set number of completions in progress; a request body may be
  at most 16 MiB; requires the inference entitlement): POST
  /v1/chat/completions, GET /v1/models, GET /v1/feeds/openrouter
- Inference billing: completions are charged by the token, at the listed
  prices, once a day (UTC) to the card your organization keeps under
  Settings, API billing (large accounts and marketplaces are invoiced
  monthly); usage in each response, and in a stream's last chunk with
  stream_options.include_usage, is what was charged. Without an active
  billing account a completion returns 402 billing_required, after a failed
  charge 402 billing_paused until it is paid, and past the organization's
  daily spend limit ($100 until an admin changes it) 402 daily_limit_reached
  until the next UTC day. Listing models and the feed are never refused for
  billing.

## Authentication

Price index requests use an API key in the X-API-Key header; the inference
routes also accept it as Authorization: Bearer (send exactly one). Customer RFQ
requests under /v1/rfq/customer use the original Auth0 bearer token. Guest RFQ
requests use the X-RFQ-Guest-Token capability header. Machine access is
available to active seats of the allocation buyer during its authorized
delivery window, after capacity acceptance and connection verification.

Create a new LiquidCompute API key during production onboarding. Omitting index_id on
custom-index requests uses your key's default index; keys with multiple index
authorizations and no default must pass index_id explicitly.

## Rate Limits

Token-bucket per key: X-RateLimit-Limit / X-RateLimit-Remaining /
X-RateLimit-Reset (estimated next-token time) after parameter validation and
authorization checks (may be omitted during rare degraded operation); 429
rate_limited is your key's limit, 429 upstream_rate_limited is the shared
upstream data source throttling — Retry-After accompanies them whenever a
retry hint is available.

## Errors

JSON envelope: {"error": {"code", "message"}} with codes: invalid_request,
unauthorized, not_found, method_not_allowed, rate_limited,
upstream_rate_limited, upstream_error, configuration_error,
service_unavailable, data_unavailable. Inference errors also carry OpenAI's
"type", and add request_too_large, concurrency_limited, model_not_found,
capacity_exhausted, warming_up, no_healthy_node, and the 402 billing codes
billing_required, billing_paused and daily_limit_reached.

Commitment pricing: GET /v1/custom-index/commitment-pricing?index_id=h100-us
requires both selected-index and private-txns entitlements, included with
Enterprise. It fits recent
reserved rates by commitment length, not future delivery dates. See the
canonical OpenAPI schema for its 120-day window, eligibility and weighting.

## GPU Test MCP Server

A remote MCP server (Streamable HTTP) runs Liquid Compute GPU acceptance tests
on NVIDIA GPU nodes you administer: https://api.liquidcompute.co/mcp

- Sign-in: OAuth 2.1 with a Liquid Compute account, scope gpu_tests. Protected
  resource metadata:
  https://api.liquidcompute.co/.well-known/oauth-protected-resource/mcp
- Tools: list_gpu_test_profiles, list_gpu_tests, create_gpu_test,
  add_gpu_test_nodes, get_gpu_test, retry_gpu_test_connection_check,
  start_gpu_test, stop_gpu_test, get_gpu_test_report, share_gpu_test_report
- add_gpu_test_nodes and start_gpu_test refuse to run until the agent passes
  the user's own confirmations; agents must never give them for the user.
- It takes no X-API-Key and limits calls per signed-in account.
- Client setup, the agent skill and plugin manifests:
  https://github.com/Liquid-Compute/gcat