Skip to main content
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

StatusMeaning
400The 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

StatusMeaning
400The 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.