Manage provider API keys and model availability

Configure API keys for Gemini, Anthropic, Groq, and OpenRouter, remove them, and list which models are available given your current configuration.

GridOS routes LLM calls through whichever providers you have configured. The endpoints on this page let you inspect provider status, save or update API keys, remove them, and discover which models are currently usable. Keys are stored locally in data/api_keys.json and persist across server restarts.

GET /settings/providers

Return the list of all known providers and whether each one is currently configured with a working API key.

Response

providers · array of objects

One entry per supported provider. Each object contains the fields below.

providers[].id · string

Machine-readable provider identifier. One of: "gemini", "anthropic", "groq", "openrouter".

providers[].display_name · string

Human-readable provider name (e.g. "Google Gemini", "Anthropic Claude").

providers[].configured · boolean

true when a valid API key is stored and the provider client initialised successfully.

providers[].masked_key · string

A masked representation of the stored key (e.g. "sk-a…b1c2"), or an empty string when no key is set. The full key is never returned.

Example

GET /settings/providers

Response

{
  "providers": [
    {
      "id": "gemini",
      "display_name": "Google Gemini",
      "configured": true,
      "masked_key": "AIza…x9Yb"
    },
    {
      "id": "anthropic",
      "display_name": "Anthropic Claude",
      "configured": true,
      "masked_key": "sk-a…b1c2"
    },
    {
      "id": "groq",
      "display_name": "Groq",
      "configured": false,
      "masked_key": ""
    },
    {
      "id": "openrouter",
      "display_name": "OpenRouter",
      "configured": false,
      "masked_key": ""
    }
  ]
}

---

POST /settings/keys/save

Save or update the API key for a provider. GridOS immediately attempts to initialise the provider client with the supplied key, so you get instant feedback if the key is syntactically invalid or the provider SDK is unavailable.

Request

provider · string · required

The provider to configure. Accepted values: "gemini", "anthropic", "groq", "openrouter".

api_key · string · required

The API key string. Must be a non-empty string. The key is persisted to data/api_keys.json and survives server restarts.

Response

status · string

"Success" when the key was saved and the provider client initialised.

provider · string

The provider ID that was updated.

configured · boolean

true when the provider client is now active and ready to handle requests.

Errors

Status	Meaning
400	The provider value is not recognised, the api_key is empty, or the provider SDK could not be initialised with the supplied key.

Example

POST /settings/keys/save
{
  "provider": "anthropic",
  "api_key": "sk-ant-api03-..."
}

Response

{
  "status": "Success",
  "provider": "anthropic",
  "configured": true
}

If you have a key set via an environment variable (e.g. ANTHROPIC_API_KEY), saving a key via this endpoint takes precedence and persists it to disk. Environment-variable keys are used only as a fallback when no disk key is present.

---

DELETE /settings/keys/

Remove the stored API key for a provider. The provider client is torn down immediately. Subsequent agent calls that require this provider will fail until a new key is saved.

Path Parameters

provider_id · string · required

The provider whose key you want to remove. Accepted values: "gemini", "anthropic", "groq", "openrouter".

Response

status · string

"Success" when the key was removed (or when no key was present for the provider — the operation is idempotent).

provider · string

The provider ID that was targeted.

Errors

Status	Meaning
400	The provider_id is not a recognised provider.

Example

DELETE /settings/keys/groq

Response

{
  "status": "Success",
  "provider": "groq"
}

Deleting a provider key does not automatically fall back to an environment variable. To restore environment-variable behaviour for that provider, remove its entry from the in-app settings and restart the server.

---

GET /models/available

List every model in the GridOS model catalog, annotated with whether it is currently available (i.e. its provider has a configured key). Also returns the resolved default model ID and the set of configured provider IDs.

Response

models · array of objects

Every model in the catalog. Each entry includes at minimum id, provider, and available (true / false).

default_model_id · string

The model ID that GridOS will use when no explicit model is requested and multiple providers are configured. null when no provider is configured.

configured_providers · array of strings

Sorted list of provider IDs that currently have a working key.

Example

GET /models/available

Response

{
  "models": [
    {
      "id": "gemini-3.1-flash-lite-preview",
      "provider": "gemini",
      "display_name": "Gemini Flash Lite",
      "available": true
    },
    {
      "id": "claude-sonnet-4-6",
      "provider": "anthropic",
      "display_name": "Claude Sonnet 4.6",
      "available": false
    },
    {
      "id": "llama-3.1-8b-instant",
      "provider": "groq",
      "display_name": "Llama 3.1 8B (Groq)",
      "available": false
    }
  ],
  "default_model_id": "gemini-3.1-flash-lite-preview",
  "configured_providers": ["gemini"]
}

Pass a model_id from this list in the model_id field of POST /agent/chat or POST /agent/chat/chain to pin a specific model for a conversation. If the model’s provider is not configured, GridOS falls back to the default model automatically.