> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/api-reference/platform-api.md). # Platform API The Platform API is the account control plane: OAuth 2.0 login, consumption API keys, trading signing keys, and account settings. It is separate from the [Consumption API](/docs/api-reference/consumption-api.md) (inference) and the [Trading API](/docs/api-reference/trading-api.md) (markets, orders, balances). Most automation flows obtain a short-lived OAuth access token here, create credentials, then call Consumption and Trading with those credentials. See [Programmatic onboarding](/docs/start-here/programmatic-onboarding.md) for the full happy path. Base URL: `https://platform.api.thegrid.ai/v1` The host also serves these endpoints under `/api/v1`, so `https://platform.api.thegrid.ai/api/v1/...` and `https://platform.api.thegrid.ai/v1/...` are equivalent. The examples in these docs use the shorter `/v1` form. Authentication uses OAuth bearer tokens from the device flow, or the browser session cookie when called from the dashboard. See [Authentication](/docs/api-reference/authentication.md#oauth-access-tokens-platform-api) for token types and how to get one. Each endpoint below lists the OAuth scope it requires; discover what a given `client_id` may request with the scopes endpoint. ## How the Platform API fits with the other APIs ```mermaid sequenceDiagram participant Client as Your integration participant Pl as Platform API participant Co as Consumption API participant Tr as Trading API Client->>Pl: Device flow login Client->>Pl: POST /v1/api-keys Pl-->>Client: consumption key (once) Client->>Co: POST /v1/chat/completions (Bearer consumption key) Client->>Pl: POST /v1/signing-keys Client->>Tr: POST /v1/orders (Ed25519 signing) ``` Inference does not accept OAuth access tokens: create a consumption API key here, then call the Consumption API with that key as Bearer. ## OAuth Device flow login ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)), token refresh, revocation ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)), scope discovery, and grant management. Public clients such as the Grid CLI use the `grid-cli-public` application; see [Programmatic onboarding](/docs/start-here/programmatic-onboarding.md#prerequisites) for how to pick a `client_id`. {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/oauth/scopes" method="get" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/oauth/device/code" method="post" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/oauth/token" method="post" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/oauth/revoke" method="post" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} Revocation ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)) takes a JSON body with a single required field, `token`, which may be either an access token (`grid_at_*`) or a refresh token (`grid_rt_*`): ```bash curl -sS -X POST "https://platform.api.thegrid.ai/v1/oauth/revoke" \ -H "Content-Type: application/json" \ -d '{"token": "grid_rt_…"}' ``` The optional `token_type_hint` (`access_token` or `refresh_token`) from RFC 7009 is accepted but not required; `client_id` is not required. Per the spec, the endpoint always returns `200` with an empty body `{}`, including for unknown or already-revoked tokens, so do not treat a `200` as proof the token existed. {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/oauth/grants" method="get" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/oauth/grants/{id}" method="delete" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} ## Consumption API keys Manage the keys used for inference on the [Consumption API](/docs/api-reference/consumption-api.md). All key endpoints, including list and show, require the `keys:manage` scope; there is no read-only key scope. The raw secret appears once in the create response, then list and show return `key: null` with only `key_prefix`. {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/api-keys" method="get" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/api-keys" method="post" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/api-keys/{id}" method="get" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/api-keys/{id}" method="patch" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/api-keys/{id}" method="delete" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} ## Trading signing keys Register Ed25519 public keys for [Trading API](/docs/api-reference/trading-api.md) request signing. Generate the keypair locally; the private key never leaves your machine. Keypair generation and the signing scheme: [Authentication](/docs/api-reference/authentication.md#trading-keys). Requires the `keys:manage` scope. {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/signing-keys" method="get" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/signing-keys" method="post" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/signing-keys/{id}" method="delete" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} ## Account settings Read account mode and funding automation settings, and switch between [Auto Mode and Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md). Reads require the `account:read` scope; mutations require `account:write` plus a verified user, accepted legal terms, and an active account. Some settings are owned by the account mode. The `GET` response lists them in `mode_managed_fields` (currently `auto_buy_enabled` and `auto_transfer_enabled`): Auto Mode forces them on, Advanced Mode follows the platform defaults, and writes that diverge from the dictated value return `403 mode_managed_setting`. Treat those fields as read-only results of the account mode. To change behavior, switch the account mode instead. {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/self/system-settings" method="get" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/self/system-settings/account-mode" method="post" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/self/system-settings/auto-buy" method="patch" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/self/system-settings/auto\_reload" method="patch" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} {% openapi src="/files/o5RxaNEwcS9RATMVYC7p" path="/self/system-settings/auto-transfer" method="patch" %} [platform-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-182588c319dc38cd132c4ed19e7b4d2c0cad1bee%2Fplatform-api-swagger.yaml?alt=media) {% endopenapi %} ## Where next * [Programmatic onboarding](/docs/start-here/programmatic-onboarding.md): end-to-end walkthrough from login to first inference call * [Authentication](/docs/api-reference/authentication.md): credential types and the Trading signing scheme * [Consumption API](/docs/api-reference/consumption-api.md): inference endpoints * [Trading API](/docs/api-reference/trading-api.md): markets, orders, accounts * [Auto Mode and Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md): what the account mode controls --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://thegrid.ai/docs/api-reference/platform-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.