# The Grid (thegrid.ai)

> Agent-facing map for what The Grid is, which docs to read, and how to call the API.
>
> The Grid (thegrid.ai) lets developers stop thinking about AI model updates. Pick an instrument such as `text-prime`, and The Grid tracks which models qualify for it, continuously benchmarks them against a published quality specification, and routes each request to the cheapest qualifying option. Pricing is set by competing suppliers on a live order book, and tokens held in the Trading account can be resold on that same book, which keeps spend tied to what a workload actually consumes.

## Start here

- Homepage: https://thegrid.ai - Pick a Grid instrument once and stop thinking about model releases, deprecations, and pricing changes. The Grid tracks qualifying models continuously and routes each request to the cheapest qualifying option.
- Pricing: https://thegrid.ai/pricing - Compare Text, Code, Agent, and Lab Latest instrument pricing on The Grid.
- Instruments: https://thegrid.ai/instruments - Choose Text, Code, or Agent instruments across Standard, Prime, and Max tiers, plus Lab Latest markets.
- About: https://thegrid.ai/about - About The Grid: how developers stop thinking about AI model updates by picking an instrument once and letting The Grid track qualifying models, benchmark them continuously, and serve each request from the cheapest qualifying option.
- Contact: https://thegrid.ai/contact - How to reach The Grid: support, sales, capacity requests, and the machine-readable endpoints to try first.
- Terminal: https://terminal.thegrid.ai - Find inference capacity for high-volume, performance-sensitive, private, regional, or custom-model workloads.
- AgentSea: https://agentsea.thegrid.ai/ - Launch supported AI coding agents locally or in the cloud, pre-wired to The Grid API.
- AgentSea agent map: https://agentsea.thegrid.ai/llms.txt
- App signup: https://app.thegrid.ai/sign-up
- Full agent context: https://thegrid.ai/llms-full.txt - Full readable context for agents: product, APIs, instruments, use cases, docs links, and disambiguation.
- Brand facts JSON: https://thegrid.ai/brand-facts.json - Structured facts about The Grid's identity, product, instruments, APIs, docs, and disambiguation.
- OpenAPI spec: https://thegrid.ai/openapi.json - OpenAPI spec for The Grid's Consumption and Trading APIs, including auth, endpoints, and instruments.
- MCP server: https://thegrid.ai/mcp - MCP server over Streamable HTTP with read-only tools for instruments, live prices, the API overview, and the docs.
- URL metadata JSON: https://thegrid.ai/url-metadata.json

## Machine-readable endpoints

| Surface | URL | Notes |
| --- | --- | --- |
| Agent map (this file) | https://thegrid.ai/llms.txt | Start here |
| Full agent context | https://thegrid.ai/llms-full.txt | Long-form product, API, and instrument context |
| Brand facts | https://thegrid.ai/brand-facts.json | Structured identity, product, and API facts |
| OpenAPI 3.0 spec | https://thegrid.ai/openapi.json | Consumption, Trading, and Platform (OAuth) endpoints |
| MCP server | https://thegrid.ai/mcp | Streamable HTTP, read-only tools, no auth |
| MCP manifest | https://thegrid.ai/.well-known/mcp.json | Manifest describing The Grid MCP server: endpoint, transport, and the tools it exposes. |
| OAuth server metadata | https://thegrid.ai/.well-known/oauth-authorization-server | RFC 8414, includes `scopes_supported` |
| OAuth protected resource | https://thegrid.ai/.well-known/oauth-protected-resource | RFC 9728, includes `scopes_supported` |
| Docs discovery | https://thegrid.ai/.well-known/docs.json | Documentation map for agents |
| URL metadata | https://thegrid.ai/url-metadata.json | Titles and descriptions for every public URL |
| Sitemap index | https://thegrid.ai/sitemap.xml | Marketing, docs, and blog sitemaps |

Marketing pages also serve a Markdown representation of themselves. Send `Accept: text/markdown` to any of https://thegrid.ai/, /pricing, /instruments, /about, or /contact, or append `.md` to the path (`https://thegrid.ai/pricing.md`). Responses carry `Vary: Accept`.

## Documentation discovery

- Docs root: https://thegrid.ai/docs
- Docs index for agents: https://thegrid.ai/docs/llms.txt
- Docs sitemap: https://thegrid.ai/docs/sitemap.xml
- Docs page sitemap: https://thegrid.ai/docs/sitemap-pages.xml
- Docs overview Markdown: https://thegrid.ai/docs/readme.md

Agents should use https://thegrid.ai/docs/llms.txt to enumerate documentation pages. Prefer Markdown URLs ending in `.md` for retrieval. If a docs page does not answer your question directly, ask the docs with:

```http
GET https://thegrid.ai/docs/readme.md?ask=<specific question>
```

## Important docs entrypoints

- [Documentation overview](https://thegrid.ai/docs/readme.md): Start here to learn The Grid, pick an instrument, and make your first API call with familiar SDKs.
- [Quickstart](https://thegrid.ai/docs/start-here/quickstart.md): Go from signup to your first Grid API call using OpenAI or Anthropic-compatible request formats.
- [Choose an instrument](https://thegrid.ai/docs/start-here/choose-an-instrument.md): Instruments are The Grid's equivalent of models: standardized task and quality tiers you pass in the model field. Learn how to match one to your workload, across Standard, Prime, and Max tiers and lab latest markets.
- [Programmatic onboarding](https://thegrid.ai/docs/start-here/programmatic-onboarding.md): Onboard an agent over HTTP: OAuth device login, create a consumption API key, and make your first inference call.
- [Auto Mode vs Advanced Mode](https://thegrid.ai/docs/start-here/auto-mode-vs-advanced-mode.md): Two ways to buy inference on The Grid. Same Consumption API, same endpoint, same errors. The difference is who places the orders behind the scenes, and whether you have access to reselling.
- [Current instruments](https://thegrid.ai/docs/instrument-specifications/current-instruments.md): Compare live Text, Code, and Agent instruments by quality floor, context, output, and latency.
- [Reselling tokens](https://thegrid.ai/docs/concepts/reselling.md): Resell unused tokens from your Trading account back on the order book.
- [Integrations](https://thegrid.ai/docs/integrations-and-best-practices/integrations.md): Set up The Grid in IDEs, coding agents, routers, and agent frameworks.
- [OpenClaw integration](https://thegrid.ai/docs/integrations-and-best-practices/integrations/openclaw.md): Set up OpenClaw with The Grid as a custom OpenAI-compatible backend, allowlist Grid instruments, and restart the gateway.
- [Hermes Agent integration](https://thegrid.ai/docs/integrations-and-best-practices/integrations/hermes-agent.md): Connect Hermes Agent to The Grid through the native Anthropic Messages API with a Grid provider block.
- [Migrating from OpenAI](https://thegrid.ai/docs/integrations-and-best-practices/migrating-from-openai.md): Switch from OpenAI by changing the base URL, API key, and model string.
- [Routing patterns](https://thegrid.ai/docs/integrations-and-best-practices/routing-patterns.md): Route workloads across various instruments: Prime by default, Max for hard tasks, Standard for volume.
- [Troubleshooting](https://thegrid.ai/docs/integrations-and-best-practices/troubleshooting.md): Fix common Grid integration issues: auth, base URLs, model strings, balance, and rate limits.
- [Any OpenAI-compatible tool](https://thegrid.ai/docs/integrations-and-best-practices/any-openai-compatible-tool.md): Generic setup for any client that can target the OpenAI Chat Completions API.
- [API overview](https://thegrid.ai/docs/api-reference/api-reference.md): Overview of The Grid's HTTP APIs, authentication, routing behavior, and runtime errors.
- [Authentication](https://thegrid.ai/docs/api-reference/authentication.md): Generate, use, and rotate API keys for The Grid's Consumption and Trading APIs.
- [Consumption API](https://thegrid.ai/docs/api-reference/consumption-api.md): Run inference through The Grid using OpenAI Chat Completions or Anthropic Messages formats.
- [Trading API](https://thegrid.ai/docs/api-reference/trading-api.md): The market side of The Grid: read instrument specs, market data, balances, and past trades, place limit orders yourself instead of letting Auto Mode buy on your behalf, or resell unused tokens back on the book.
- [Platform API](https://thegrid.ai/docs/api-reference/platform-api.md): OAuth login, programmatic API key and signing key management, and account settings.
- [Errors and rate limits](https://thegrid.ai/docs/api-reference/errors-and-rate-limits.md): Understand Grid API errors, retryable failures, balance issues, and rate limits.
- [Data handling and privacy](https://thegrid.ai/docs/data-handling-and-privacy/data-handling-and-privacy.md): What The Grid stores, what it does not, and how prompts, credentials, and usage records are handled.

## API quick facts

- OpenAI-compatible base URL: `https://api.thegrid.ai/v1`
- OpenAI-compatible auth: `Authorization: Bearer YOUR_GRID_API_KEY`
- Anthropic-compatible Messages beta base URL: `https://messages-beta.api.thegrid.ai/v1`
- Anthropic-compatible auth: `x-api-key: YOUR_GRID_API_KEY`
- Platform API base URL (OAuth, key creation, settings): `https://platform.api.thegrid.ai/v1`
- Use an instrument id as the model, for example `text-prime`, `code-prime`, or `agent-standard`, or a lab latest market id such as `claude-opus-latest`.

## Onboard programmatically (agents and integrations)

Agents can self-provision and start running inference without a human copying a key from the dashboard. Log in with OAuth, mint a consumption key, then call the Consumption API:

1. Request a device code: `POST https://platform.api.thegrid.ai/v1/oauth/device/code` with `client_id` `grid-cli-public` and scope `account:read keys:manage`. Approve once at the returned `verification_uri`.
2. Poll for tokens: `POST https://platform.api.thegrid.ai/v1/oauth/token` until you receive an `access_token` (`grid_at_*`). Tokens last about one hour; refresh with `grant_type=refresh_token`.
3. Create a consumption key: `POST https://platform.api.thegrid.ai/v1/api-keys` with the access token as Bearer. The secret is returned once, so store it immediately.
4. Run inference: `POST https://api.thegrid.ai/v1/chat/completions` with that key as Bearer and `text-prime` as the model.

Full walkthrough: https://thegrid.ai/docs/start-here/programmatic-onboarding.md
Platform API reference: https://thegrid.ai/docs/api-reference/platform-api.md

### Scopes

Request only what you need. The live catalog is `GET https://platform.api.thegrid.ai/v1/oauth/scopes`; discovery metadata is published at https://thegrid.ai/.well-known/oauth-authorization-server (RFC 8414) and https://thegrid.ai/.well-known/oauth-protected-resource (RFC 9728).

- `account:read`: Read account profile, balances, and related account data.
- `account:write`: Update account settings and perform account mutations.
- `trade:read`: Read orders, trades, positions, and trading history.
- `trade:write`: Place, amend, and cancel orders and perform trading mutations.
- `supply:read`: Read supply issuance, balances, and supply account data.
- `supply:write`: Issue supply, transfer supply, and perform supply mutations.
- `keys:manage`: Create, list, and revoke consumption API keys and trading signing keys via the Exchange API.

### Getting started without a sales call

- Free to start: $25 signup credit at https://app.thegrid.ai/sign-up. No contract, no minimum commitment.
- Self-serve keys: `POST https://platform.api.thegrid.ai/v1/api-keys` mints a consumption key programmatically once you hold an OAuth access token.
- No hosted sandbox, but you can build without spending: the read-only diagnostics endpoints (`grid diagnostics`) verify auth, clock skew, and configuration, and the Grid CLI repository ships a local mock server for the Trading API. Docs: https://thegrid.ai/docs/api-reference/diagnostics.md

## MCP server

The Grid runs an MCP server over Streamable HTTP at `https://thegrid.ai/mcp`. It is stateless, unauthenticated, and read-only: POST JSON-RPC 2.0 messages, no session id, no server-initiated stream. Tools:

- `list_instruments`: List The Grid instruments with live spot prices, quality floors, context and output limits.
- `get_instrument`: Full detail for one instrument, including model distribution and use cases.
- `ask_docs`: Ask a natural-language question against The Grid documentation and get sourced excerpts.
- `get_api_overview`: Base URLs, auth schemes, OAuth scopes, and programmatic onboarding steps.

Manifest: https://thegrid.ai/.well-known/mcp.json

## Command-line tool

The Grid CLI (`grid`) covers OAuth device login, key management, market data, orders, and `grid diagnostics` for zero-spend setup checks. It is not on npm, PyPI, or Homebrew; install it from source:

```bash
git clone https://github.com/the-gridai/grid-cli.git
cd grid-cli
npm install
npm run build
npm link .          # makes the `grid` command available globally
```

An install script (`bash grid/install/install.sh`, or `grid/install/install.ps1` on Windows) and prebuilt macOS and Linux binaries on GitHub Releases (https://github.com/the-gridai/grid-cli/releases) are also available; from source is the most reliable path.

Source: https://github.com/the-gridai/grid-cli. Command reference: https://thegrid.ai/docs/api-reference/diagnostics.md

## API versioning and deprecation

Every public surface is versioned in the URL path under `/v1`. Breaking changes ship under a new version prefix rather than in place; endpoints under an existing prefix may gain fields, but existing fields are not removed or retyped without a version bump. An endpoint scheduled for removal is announced with the `Deprecation` header (RFC 9745), a `Sunset` header (RFC 8594) carrying the date it stops responding, and a `Link` header pointing at the successor. Deprecated operations are also marked `deprecated: true` in https://thegrid.ai/openapi.json.

## Current instruments

Prices and recently served models change with the market. For live data, query `GET https://api.thegrid.ai/v1/models` (no auth required).

- Text Standard (`text-standard`): Price-optimized, high-throughput text. $0.035/1M tokens trailing 30-day blended average. Save up to 87%.
- Text Prime (`text-prime`): Reliable models for everyday tasks. $0.120/1M tokens trailing 30-day blended average. Save up to 78%.
- Text Max (`text-max`): Frontier models for complex reasoning. $1.709/1M tokens trailing 30-day blended average. Save up to 16%.
- Code Standard (`code-standard`): Price-optimized, high-throughput code. $0.035/1M tokens trailing 30-day blended average. Save up to 79%.
- Code Prime (`code-prime`): Reliable models for daily coding work. $0.120/1M tokens trailing 30-day blended average. Save up to 78%.
- Code Max (`code-max`): Frontier models for complex coding tasks. $1.709/1M tokens trailing 30-day blended average. Save up to 50%.
- Agent Standard (`agent-standard`): Price-optimized, high-throughput agents. $0.035/1M tokens trailing 30-day blended average. Save up to 79%.
- Agent Prime (`agent-prime`): Reliable models for daily agent work. $0.120/1M tokens trailing 30-day blended average. Save up to 82%.
- Agent Max (`agent-max`): Frontier models for complex agent tasks. $1.709/1M tokens trailing 30-day blended average. Save up to 16%.
- GPT Sol Latest (`gpt-sol-latest`): Latest qualifying route for GPT frontier supply. $1.821/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- Claude Opus Latest (`claude-opus-latest`): Latest qualifying route for Claude Opus frontier supply. $1.709/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- Gemini Pro Latest (`gemini-pro-latest`): Latest qualifying route for Gemini Pro frontier supply. $0.656/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- MiniMax Latest (`minimax-latest`): Latest qualifying route for MiniMax supply. $0.118/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- GLM Latest (`glm-latest`): Latest qualifying route for GLM supply. $0.355/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- DeepSeek Pro Latest (`deepseek-pro-latest`): Latest qualifying route for DeepSeek Pro supply. $0.444/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- Kimi Latest (`kimi-latest`): Latest qualifying route for Kimi supply. $1.000/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.
- ByteDance Pro Latest (`bytedance-pro-latest`): Latest qualifying route for ByteDance Pro supply. $0.220/1M tokens, usage-mix blended launch rate. No provider-discount percentage is claimed.

## Terminal

Terminal (https://terminal.thegrid.ai) is for teams that need inference capacity for a specific workload: high volume, performance, privacy, region, or a custom model. Send a capacity request; sales follows up by email. Terminal is not the Grid app and does not create a Grid account.

## Disambiguation

The Grid is the AI inference API at thegrid.ai, built by Spectral Labs, that lets developers stop thinking about model updates. It is not Grid AI (grid.ai / Lightning AI), GridAI Technologies (NASDAQ: GRDX), DGrid (dgrid.ai), or the defunct The Grid website builder.