Platform API

Reference for The Grid Platform API at cortex.thegrid.ai. OAuth 2.0 device login for agents, programmatic consumption and trading key management, and account settings endpoints with full request and r

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 (inference) and the Trading API (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 for the full happy path.

Base URL: https://cortex.thegrid.ai/v1

The host also serves these endpoints under /api/v1, so https://cortex.thegrid.ai/api/v1/... and https://cortex.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 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

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), token refresh, revocation (RFC 7009), scope discovery, and grant management. Public clients such as the Grid CLI use the grid-cli-public application; see Programmatic onboarding for how to pick a client_id.

List OAuth scopes

get

Lists all platform scopes. Pass client_id to see only the scopes a registered OAuth application may request. No authentication required.

Query parameters

client_idstringOptionalExample: grid-cli-public

Responses

200

Scope catalog

application/json

401

Unknown client_id

application/json

get/oauth/scopes

GET /v1/oauth/scopes HTTP/1.1
Host: cortex.thegrid.ai
Accept: */*

{
  "data": [
    {
      "name": "keys:manage",
      "description": "text"
    }
  ]
}

Request a device code (RFC 8628)

post

Starts the device authorization flow. The user approves the listed scopes at verification_uri.

Body

client_idstringRequiredExample: grid-cli-public

scopestringRequiredExample: account:read account:write keys:manage

Responses

200

Device authorization created

application/json

device_codestringOptional

user_codestringOptional

verification_uristringOptionalExample: https://app.thegrid.ai/activate

expires_inintegerOptional

Seconds until the device code expires

intervalintegerOptional

Minimum seconds between token polls

post/oauth/device/code

POST /v1/oauth/device/code HTTP/1.1
Host: cortex.thegrid.ai
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "client_id": "grid-cli-public",
  "scope": "account:read account:write keys:manage"
}

200

Device authorization created

{
  "device_code": "text",
  "user_code": "text",
  "verification_uri": "https://app.thegrid.ai/activate",
  "expires_in": 1,
  "interval": 1
}

Exchange a device code or refresh token for tokens

post

Poll with grant_type urn:ietf:params:oauth:grant-type:device_code until the user approves, or refresh an expired access token with grant_type refresh_token.

While polling, a 400 response carries an OAuthError body. Handle each error code distinctly: authorization_pending (keep polling at interval), slow_down (increase the interval by 5 seconds, then keep polling), access_denied (user declined; stop), and expired_token (device code expired; restart the device flow). Any other error (e.g. invalid_grant) is terminal.

Refresh tokens may rotate: persist whatever refresh_token comes back in the response and discard the previous one. Refresh about 60 seconds before expires_in elapses to absorb clock skew, and on a 401/403 invalid_token from a resource endpoint, refresh once and retry.

Body

grant_typestring · enumRequiredPossible values:

client_idstringRequired

device_codestringOptional

Required for the device_code grant

refresh_tokenstringOptional

Required for the refresh_token grant

Responses

200

Token pair issued

application/json

access_tokenstringOptional

Bearer token, prefixed grid_at_

refresh_tokenstringOptional

Refresh token, prefixed grid_rt_

token_typestringOptionalExample: Bearer

expires_inintegerOptional

Access token lifetime in seconds (3600)

scopestringOptionalExample: account:read keys:manage

400

Polling or refresh error. The error field is one of authorization_pending, slow_down, access_denied, expired_token, or invalid_grant.

application/json

post/oauth/token

POST /v1/oauth/token HTTP/1.1
Host: cortex.thegrid.ai
Content-Type: application/json
Accept: */*
Content-Length: 124

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "client_id": "text",
  "device_code": "text",
  "refresh_token": "text"
}

{
  "access_token": "text",
  "refresh_token": "text",
  "token_type": "Bearer",
  "expires_in": 1,
  "scope": "account:read keys:manage"
}

Revoke a token (RFC 7009)

post

Revokes an access or refresh token. Send a JSON body with the token to revoke. token_type_hint is optional and client_id is not required. Always returns 200 with an empty body, even for unknown or already-revoked tokens, so a 200 is not proof the token existed.

Body

tokenstringRequired

An access token (grid_at_) or refresh token (grid_rt_)

token_type_hintstring · enumOptional

Optional RFC 7009 hint. Accepted but not required.

Possible values:

Responses

200

Revoked (or unknown token, per RFC 7009). Body is empty ({}).

No content

post/oauth/revoke

POST /v1/oauth/revoke HTTP/1.1
Host: cortex.thegrid.ai
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "token": "text",
  "token_type_hint": "access_token"
}

200

Revoked (or unknown token, per RFC 7009). Body is empty ({}).

No content

Revocation (RFC 7009) 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_*):

curl -sS -X POST "https://cortex.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.

List active OAuth grants

get

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Responses

200

Grants for the authenticated user

application/json

401

Authentication required

get/oauth/grants

GET /v1/oauth/grants HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "application_name": "text",
      "scopes": [
        "text"
      ],
      "inserted_at": "2026-07-10T16:18:55.446Z"
    }
  ]
}

Revoke a grant

delete

Revokes the grant and invalidates its tokens.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Path parameters

idstring · uuidRequired

Responses

204

Grant revoked

No content

404

Grant not found

delete/oauth/grants/{id}

DELETE /v1/oauth/grants/{id} HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Consumption API keys

Manage the keys used for inference on the Consumption API. 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.

List consumption API keys

get

Raw secrets are never returned on list. Requires the keys:manage scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Responses

200

Keys with key set to null and key_prefix populated

application/json

get/api-keys

GET /v1/api-keys HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Keys with key set to null and key_prefix populated

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "key": "text",
      "key_prefix": "text",
      "inserted_at": "2026-07-10T16:18:55.446Z"
    }
  ]
}

Create a consumption API key

post

The raw secret is returned once in data.key. Store it immediately. Requires the keys:manage scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Body

Responses

201

Key created, raw secret in data.key

application/json

post/api-keys

POST /v1/api-keys HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "api_key": {
    "name": "my-agent"
  }
}

201

Key created, raw secret in data.key

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "key": "text",
    "key_prefix": "text",
    "inserted_at": "2026-07-10T16:18:55.446Z"
  }
}

Show one key

get

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Path parameters

idstring · uuidRequired

Responses

200

Key metadata, raw secret not included

No content

get/api-keys/{id}

GET /v1/api-keys/{id} HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Key metadata, raw secret not included

No content

Update key metadata

patch

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Path parameters

idstring · uuidRequired

Body

Responses

204

Updated

No content

patch/api-keys/{id}

PATCH /v1/api-keys/{id} HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "api_key": {
    "name": "text"
  }
}

204

Updated

No content

Revoke a key

delete

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Path parameters

idstring · uuidRequired

Responses

204

Revoked

No content

delete/api-keys/{id}

DELETE /v1/api-keys/{id} HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Revoked

No content

Trading signing keys

Register Ed25519 public keys for Trading API request signing. Generate the keypair locally; the private key never leaves your machine. Keypair generation and the signing scheme: Authentication. Requires the keys:manage scope.

List registered signing keys

get

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Responses

200

Registered Ed25519 public keys

application/json

get/signing-keys

GET /v1/signing-keys HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Registered Ed25519 public keys

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "label": "text",
      "fingerprint": "text",
      "inserted_at": "2026-07-10T16:18:55.446Z"
    }
  ]
}

Register an Ed25519 public key

post

Generate the keypair locally; only the public key is registered. The private key never leaves your machine. Requires the keys:manage scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Body

Responses

201

Registered. Response includes the fingerprint used as x-thegrid-fingerprint.

No content

422

Invalid public key

post/signing-keys

POST /v1/signing-keys HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "signing_key": {
    "label": "my-bot",
    "public_key": "text"
  }
}

No content

Revoke a signing key

delete

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Path parameters

idstring · uuidRequired

Responses

204

Revoked

No content

delete/signing-keys/{id}

DELETE /v1/signing-keys/{id} HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Revoked

No content

Account settings

Read account mode and funding automation settings, and switch between Auto Mode and Advanced Mode. 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.

Read account settings

get

Returns account mode and funding automation settings. Fields listed in mode_managed_fields are dictated by the account mode and are read-only through this API. Requires the account:read scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Responses

200

Current settings

application/json

get/self/system-settings

GET /v1/self/system-settings HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Current settings

{
  "data": {
    "account_mode": "easy",
    "auto_transfer_enabled": true,
    "auto_buy_enabled": true,
    "auto_buy_quantity": 1,
    "auto_buy_trigger_threshold": 1,
    "auto_reload_enabled": true,
    "auto_reload_threshold_usd": "text",
    "auto_reload_amount_usd": "text",
    "auto_reload_monthly_limit_usd": "text",
    "mode_managed_fields": [
      "auto_buy_enabled",
      "auto_transfer_enabled"
    ]
  }
}

Switch account mode

post

Switches between auto (easy) and advanced mode. Switching back to easy fails with 409 while open orders exist. Requires the account:write scope, a verified user, accepted legal terms, and an active account.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Body

modestring · enumRequiredPossible values:

Responses

204

Mode switched

No content

409

Already in the requested mode, or open orders block the switch

422

Missing or invalid mode

post/self/system-settings/account-mode

POST /v1/self/system-settings/account-mode HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "mode": "easy"
}

No content

Set auto-buy

patch

Idempotent. auto_buy_enabled is mode-managed: the account mode dictates its value, so only the dictated value is accepted; anything else returns 403 mode_managed_setting. Requires the account:write scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Body

auto_buy_enabledbooleanOptional

Responses

200

Current settings, same shape as GET

No content

403

Value diverges from the mode-dictated value (mode_managed_setting)

patch/self/system-settings/auto-buy

PATCH /v1/self/system-settings/auto-buy HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "auto_buy_enabled": true
}

No content

Update auto-reload (USD threshold reload)

patch

Updates only auto_reload_* fields. Enabling auto-reload requires both USD fields, in the request or already stored. Requires the account:write scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Body

auto_reload_enabledbooleanOptional

auto_reload_threshold_usdstringOptionalExample: 10

auto_reload_amount_usdstringOptionalExample: 100

auto_reload_monthly_limit_usdstringOptionalExample: 500

Responses

200

Current settings, same shape as GET

No content

422

Validation error (missing USD fields, invalid ranges, limit below amount)

patch/self/system-settings/auto_reload

PATCH /v1/self/system-settings/auto_reload HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 130

{
  "auto_reload_enabled": true,
  "auto_reload_threshold_usd": "10",
  "auto_reload_amount_usd": "100",
  "auto_reload_monthly_limit_usd": "500"
}

No content

Set auto-transfer

patch

auto_transfer_enabled is mode-managed: only the value dictated by the account mode is accepted (403 mode_managed_setting otherwise). Send auto_transfer_override null to clear a stored override and follow the platform default. Requires the account:write scope.

Authorizations

AuthorizationstringRequired

OAuth access token issued by the device or authorization-code flow. Tokens are prefixed grid_at_. Each endpoint lists the scope it requires.

Body

auto_transfer_enabledbooleanOptional

auto_transfer_overrideboolean · nullableOptional

Responses

200

Current settings, same shape as GET

No content

403

Value diverges from the mode-dictated value (mode_managed_setting)

patch/self/system-settings/auto-transfer

PATCH /v1/self/system-settings/auto-transfer HTTP/1.1
Host: cortex.thegrid.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "auto_transfer_enabled": true,
  "auto_transfer_override": true
}

No content

Where next

Programmatic onboarding: end-to-end walkthrough from login to first inference call
Authentication: credential types and the Trading signing scheme
Consumption API: inference endpoints
Trading API: markets, orders, accounts
Auto Mode and Advanced Mode: what the account mode controls

PreviousTrading API NextDiagnostics

Last updated 3 days ago

Was this helpful?