Provider & Model API

Endpoints for browsing the model catalog and managing LLM provider configurations.

Model Catalog Endpoints

LibreFang maintains a built-in catalog of 130+ models across 49 providers. These endpoints allow you to browse available models, check provider authentication status, and resolve model aliases.

GET /api/models

List the full model catalog. Returns all known models with their provider, tier, context window, and pricing information.

Response 200 OK:

{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "display_name": "Claude Sonnet 4",
      "tier": "frontier",
      "context_window": 200000,
      "input_cost_per_1m": 3.0,
      "output_cost_per_1m": 15.0,
      "supports_tools": true,
      "supports_vision": true,
      "supports_streaming": true
    },
    {
      "id": "gemini-2.5-flash",
      "provider": "gemini",
      "display_name": "Gemini 2.5 Flash",
      "tier": "smart",
      "context_window": 1048576,
      "input_cost_per_1m": 0.15,
      "output_cost_per_1m": 0.6,
      "supports_tools": true,
      "supports_vision": true,
      "supports_streaming": true
    }
  ],
  "total": 130
}

GET /api/models/aliases

List all model aliases. Aliases provide short names that resolve to full model IDs (e.g., sonnet resolves to claude-sonnet-4-20250514).

Response 200 OK:

{
  "aliases": {
    "sonnet": "claude-sonnet-4-20250514",
    "opus": "claude-opus-4-20250514",
    "haiku": "claude-3-5-haiku-20241022",
    "flash": "gemini-2.5-flash",
    "gpt4": "gpt-4o",
    "llama": "llama-3.3-70b-versatile",
    "deepseek": "deepseek-chat",
    "grok": "grok-2",
    "jamba": "jamba-1.5-large"
  },
  "total": 23
}

POST /api/models/aliases

Create a new model alias.

Request Body:

{
  "alias": "mymodel",
  "model_id": "llama-3.3-70b-versatile"
}

DELETE /api/models/aliases/{alias}

Delete a model alias.

POST /api/models/custom

Register a custom model definition.

Request Body:

{
  "id": "my-local-model",
  "provider": "ollama",
  "display_name": "My Local LLM",
  "context_window": 32768
}

DELETE /api/models/custom/{id}

Remove a custom model definition. The id parameter supports slashes (e.g., ollama/my-model).

GET /api/models/{id}

Get detailed information about a specific model. The id parameter supports slashes.

Response 200 OK:

{
  "id": "llama-3.3-70b-versatile",
  "provider": "groq",
  "display_name": "Llama 3.3 70B",
  "tier": "fast",
  "context_window": 131072,
  "input_cost_per_1m": 0.59,
  "output_cost_per_1m": 0.79,
  "supports_tools": true,
  "supports_vision": false,
  "supports_streaming": true
}

POST /api/catalog/update

Trigger an update of the model catalog from the remote registry.

GET /api/catalog/status

Get the current catalog version, last update time, and available updates.

Provider Configuration Endpoints

Manage LLM provider API keys at runtime without editing config files or restarting the daemon.

GET /api/providers

List all known LLM providers and their authentication status. Auth status is detected by checking environment variable presence (never reads secret values).

Response 200 OK:

{
  "providers": [
    {
      "name": "anthropic",
      "display_name": "Anthropic",
      "auth_status": "configured",
      "env_var": "ANTHROPIC_API_KEY",
      "base_url": "https://api.anthropic.com",
      "model_count": 3
    },
    {
      "name": "groq",
      "display_name": "Groq",
      "auth_status": "configured",
      "env_var": "GROQ_API_KEY",
      "base_url": "https://api.groq.com/openai",
      "model_count": 4
    },
    {
      "name": "ollama",
      "display_name": "Ollama",
      "auth_status": "no_key_needed",
      "base_url": "http://localhost:11434",
      "model_count": 0
    }
  ],
  "total": 28
}

GET /api/providers/ollama/detect

Auto-detect a locally running Ollama instance and enumerate its available models.

POST /api/providers/github-copilot/oauth/start

Initiate GitHub Copilot device OAuth flow. Returns a device_code and user_code for the user to enter at github.com/login/device.

GET /api/providers/github-copilot/oauth/poll/{poll_id}

Poll the OAuth device flow status. Returns pending, authorized, or expired.

GET /api/providers/{name}

Get configuration and status for a specific provider.

POST /api/providers/{name}/key

Set an API key for a provider. The key is stored securely and takes effect immediately.

Request Body:

{
  "api_key": "sk-..."
}

Response 200 OK:

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

DELETE /api/providers/{name}/key

Remove the API key for a provider. Agents using this provider will fall back to the FallbackDriver or fail.

Response 200 OK:

{
  "status": "removed",
  "provider": "anthropic"
}

POST /api/providers/{name}/test

Test provider connectivity by making a minimal API call. Verifies that the configured API key is valid and the provider endpoint is reachable.

Response 200 OK:

{
  "status": "ok",
  "provider": "anthropic",
  "latency_ms": 245,
  "model_tested": "claude-sonnet-4-20250514"
}

PUT /api/providers/{name}/url

Override the base URL for a provider (useful for self-hosted or proxy endpoints).

Request Body:

{
  "url": "https://my-openai-proxy.example.com/v1"
}