### Run HTTP Server

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/INDEX.md

Starts the Catwalk HTTP server. Ensure you are in the project root directory.

```bash
go run .
```

--------------------------------

### Response Body for /v2/providers (200 OK)

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Example JSON response body for a successful GET request to the /v2/providers endpoint, detailing AI provider configurations and their models.

```json
[
  {
    "name": "Anthropic",
    "id": "anthropic",
    "api_key": "$ANTHROPIC_API_KEY",
    "api_endpoint": "$ANTHROPIC_API_ENDPOINT",
    "type": "anthropic",
    "default_large_model_id": "claude-sonnet-4-6",
    "default_small_model_id": "claude-haiku-4-5-20251001",
    "models": [
      {
        "id": "claude-sonnet-4-6",
        "name": "Claude Sonnet 4.6",
        "cost_per_1m_in": 3.0,
        "cost_per_1m_out": 15.0,
        "cost_per_1m_in_cached": 3.75,
        "cost_per_1m_out_cached": 0.3,
        "context_window": 1000000,
        "default_max_tokens": 128000,
        "can_reason": true,
        "reasoning_levels": ["low", "medium", "high", "max"],
        "default_reasoning_effort": "high",
        "supports_attachments": true,
        "options": {
          "temperature": null,
          "top_p": null
        }
      }
    ]
  },
  {
    "name": "OpenAI",
    "id": "openai",
    "api_key": "$OPENAI_API_KEY",
    "api_endpoint": "https://api.openai.com/v1",
    "type": "openai",
    "default_large_model_id": "gpt-4o",
    "default_small_model_id": "gpt-4o-mini",
    "models": []
  }
]
```

--------------------------------

### Filter Providers by OpenAI-Compatible Type

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/providers-list.md

This example demonstrates how to filter a list of providers to find only those that are compatible with the OpenAI protocol. It initializes a client, fetches providers, and then iterates to collect matching ones.

```go
client := catwalk.New()
providers, _ := client.GetProviders(context.Background(), "")

openaiCompat := []catwalk.Provider{}
for _, p := range providers {
    if p.Type == catwalk.TypeOpenAICompat {
        openaiCompat = append(openaiCompat, p)
    }
}
```

--------------------------------

### Configure HTTP Server Port

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/configuration.md

Sets the listening address for the HTTP server. This example binds to all interfaces on port 8080.

```go
server := &http.Server{
    Addr: ":8080",
    ...
}
```

--------------------------------

### Create Catwalk Client with Default URL

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Instantiates the Catwalk HTTP client using the default service URL. This is the simplest way to start interacting with the Catwalk API.

```go
c := catwalk.New()
```

--------------------------------

### Provider Configuration JSON Example

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/configuration.md

Defines the structure for a provider's configuration file, including API details, model information, and cost parameters. This JSON is embedded directly into the binary.

```json
{
  "name": "Provider Name",
  "id": "provider-id",
  "api_key": "$PROVIDER_API_KEY",
  "api_endpoint": "https://api.provider.com/v1",
  "type": "openai-compat",
  "default_large_model_id": "model-name",
  "default_small_model_id": "model-name-small",
  "models": [
    {
      "id": "model-id",
      "name": "Model Name",
      "cost_per_1m_in": 1.0,
      "cost_per_1m_out": 5.0,
      "cost_per_1m_in_cached": 0.5,
      "cost_per_1m_out_cached": 2.5,
      "context_window": 128000,
      "default_max_tokens": 4096,
      "can_reason": false,
      "supports_attachments": false,
      "options": {}
    }
  ]
}
```

--------------------------------

### GET /metrics

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Prometheus metrics endpoint for monitoring the Catwalk service.

```APIDOC
## GET /metrics

### Description
Prometheus metrics endpoint for monitoring.

### Method
GET

### Endpoint
/metrics

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8080/metrics | grep catwalk_providers_requests_total
```

### Response
#### Success Response (200)
- **Format**: Prometheus text format

### Metrics Exposed
- `catwalk_providers_requests_total` — Total number of requests to /v2/providers endpoint
```

--------------------------------

### GET /metrics

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Exposes Prometheus metrics in text format for monitoring and observability. Includes standard Go runtime and OS process metrics.

```APIDOC
## GET /metrics

### Description
Exposes Prometheus metrics in text format for monitoring and observability. Includes standard Go runtime and OS process metrics.

### Method
GET

### Endpoint
`http://localhost:8080/metrics`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response (200 OK)
- **Status Code**: 200
- **Content-Type**: `text/plain; version=0.0.4`
- **Body**: Prometheus text format metrics

```
# HELP catwalk_providers_requests_total Total number of requests to the providers endpoint
# TYPE catwalk_providers_requests_total counter
catwalk_providers_requests_total 42
```

### Metrics Exposed
- **`catwalk_providers_requests_total`** (Counter) - Total number of successful requests to /v2/providers (200 status)
- **`go_*`** (Various) - Standard Go runtime metrics (goroutines, memory, etc.)
- **`process_*`** (Various) - OS process metrics (CPU, memory, file descriptors)
```

--------------------------------

### Configure Prometheus Request Counter

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/configuration.md

Initializes a Prometheus counter metric for tracking requests. This example sets up a counter named 'requests_total' within the 'catwalk' namespace and 'providers' subsystem.

```go
var counter = promauto.NewCounter(prometheus.CounterOpts{
    Namespace: "catwalk",
    Subsystem: "providers",
    Name:      "requests_total",
    Help:      "Total number of requests to the providers endpoint",
})
```

--------------------------------

### GET /health

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Liveness probe endpoint for Kubernetes and load balancers. Returns OK status.

```APIDOC
## GET /health

### Description
Liveness probe endpoint for Kubernetes and load balancers. Returns OK status.

### Method
GET

### Endpoint
`http://localhost:8080/health`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response (200 OK)
- **Status Code**: 200
- **Content-Type**: `text/plain`
- **Body**: `OK`
```

--------------------------------

### GET /v2/providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Retrieves all available AI provider configurations with their models and capabilities. Supports conditional requests using the If-None-Match header.

```APIDOC
## GET /v2/providers

### Description
Retrieves all available AI provider configurations with their models and capabilities. Supports conditional requests using the If-None-Match header.

### Method
GET or HEAD

### Endpoint
`http://localhost:8080/v2/providers`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Headers
- **If-None-Match** (string) - Optional - ETag from previous response; server returns 304 if unchanged

### Request Example
```bash
# Successful request with conditional caching
curl -i -H "If-None-Match: \"abc123\"" http://localhost:8080/v2/providers

# If unchanged, returns 304
# If changed, returns 200 with new ETag header

# HEAD request (headers only)
curl -I http://localhost:8080/v2/providers
```

### Response
#### Success Response (200 OK)
- **Content-Type**: `application/json`
- **Body**: Array of provider objects

```json
[
  {
    "name": "Anthropic",
    "id": "anthropic",
    "api_key": "$ANTHROPIC_API_KEY",
    "api_endpoint": "$ANTHROPIC_API_ENDPOINT",
    "type": "anthropic",
    "default_large_model_id": "claude-sonnet-4-6",
    "default_small_model_id": "claude-haiku-4-5-20251001",
    "models": [
      {
        "id": "claude-sonnet-4-6",
        "name": "Claude Sonnet 4.6",
        "cost_per_1m_in": 3.0,
        "cost_per_1m_out": 15.0,
        "cost_per_1m_in_cached": 3.75,
        "cost_per_1m_out_cached": 0.3,
        "context_window": 1000000,
        "default_max_tokens": 128000,
        "can_reason": true,
        "reasoning_levels": ["low", "medium", "high", "max"],
        "default_reasoning_effort": "high",
        "supports_attachments": true,
        "options": {
          "temperature": null,
          "top_p": null
        }
      }
    ]
  },
  {
    "name": "OpenAI",
    "id": "openai",
    "api_key": "$OPENAI_API_KEY",
    "api_endpoint": "https://api.openai.com/v1",
    "type": "openai",
    "default_large_model_id": "gpt-4o",
    "default_small_model_id": "gpt-4o-mini",
    "models": []
  }
]
```

#### Response Headers
- **Content-Type**: `application/json`
- **ETag**: Hash of response body for caching

#### Response (304 Not Modified)
- **Status Code**: 304
- **Condition**: Client sent `If-None-Match` header with ETag matching server state
- **Headers**: ETag: Same as the request If-None-Match value
- **Body**: Empty

#### Response (405 Method Not Allowed)
- **Status Code**: 405
- **Condition**: Request method is not GET or HEAD
- **Body**: `Method not allowed`
```

--------------------------------

### Get Embedded Providers (Offline Access)

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/README.md

Demonstrates how to retrieve provider data using the embedded package for offline access, bypassing network calls.

```go
providers := embedded.GetAll()  // No network call
```

--------------------------------

### Get Default Models for Provider

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Retrieves the default large and small models configured for a given provider. Returns an error if default models are not found.

```go
func getDefaultModels(provider *catwalk.Provider) (*catwalk.Model, *catwalk.Model, error) {
    var large, small *catwalk.Model
    
    for i := range provider.Models {
        if provider.Models[i].ID == provider.DefaultLargeModelID {
            large = &provider.Models[i]
        }
        if provider.Models[i].ID == provider.DefaultSmallModelID {
            small = &provider.Models[i]
        }
    }
    
    if large == nil || small == nil {
        return nil, nil, fmt.Errorf("default models not found for %s", provider.Name)
    }
    
    return large, small, nil
}

// Usage
large, small, err := getDefaultModels(anthropic)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Large model: %s\n", large.Name)
fmt.Printf("Small model: %s\n", small.Name)
```

--------------------------------

### Get Known Provider Types

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/types.md

Retrieves a slice of all supported provider protocol types. Useful for understanding the different types of providers available.

```go
func KnownProviderTypes() []Type
```

```go
for _, providerType := range catwalk.KnownProviderTypes() {
    fmt.Println(providerType)
}
```

--------------------------------

### Provider Struct Definition

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/types.md

Defines the configuration for an AI provider, including its models and connection details. Used to represent complete AI provider setups.

```go
type Provider struct {
    Name                string            `json:"name"`
    ID                  InferenceProvider `json:"id"`
    APIKey              string            `json:"api_key,omitempty"`
    APIEndpoint         string            `json:"api_endpoint,omitempty"`
    Type                Type              `json:"type,omitempty"`
    DefaultLargeModelID string            `json:"default_large_model_id,omitempty"`
    DefaultSmallModelID string            `json:"default_small_model_id,omitempty"`
    Models              []Model           `json:"models,omitempty"`
    DefaultHeaders      map[string]string `json:"default_headers,omitempty"`
}
```

--------------------------------

### Get All Known Provider Types

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Returns a slice of all recognized Type identifiers for inference providers. This helps in understanding the different protocols supported.

```go
knownTypes := catwalk.KnownProviderTypes()
```

--------------------------------

### Check Catwalk Health

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

A simple liveness probe endpoint. Use GET method to check if the service is running. Expects 'OK' as a response body.

```bash
curl http://localhost:8080/health
# Output: OK
```

--------------------------------

### Get All Providers from Internal Registry

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Retrieves all registered providers directly from the internal provider management system. This bypasses the network client and uses embedded configurations.

```go
allProviders := providers.GetAll()
```

--------------------------------

### Retrieve All Providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Fetches a list of all available providers in JSON format. Supports ETag caching for efficient requests. Use GET or HEAD method.

```json
[
  {
    "name": "Anthropic",
    "id": "anthropic",
    "type": "anthropic",
    "api_key": "$ANTHROPIC_API_KEY",
    "api_endpoint": "$ANTHROPIC_API_ENDPOINT",
    "default_large_model_id": "claude-sonnet-4-6",
    "default_small_model_id": "claude-haiku-4-5-20251001",
    "models": [
      {
        "id": "claude-sonnet-4-6",
        "name": "Claude Sonnet 4.6",
        "cost_per_1m_in": 3,
        "cost_per_1m_out": 15,
        ...
      }
    ]
  }
]
```

--------------------------------

### Get All Providers from Embedded Configuration

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Provides offline access to all embedded provider configurations. This function acts as a thin wrapper around the internal provider registry's GetAll function.

```go
embeddedProviders := embedded.GetAll()
```

--------------------------------

### Error Response Body for /v2/providers (405 Method Not Allowed)

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Example plain text response body when a request to /v2/providers uses a method other than GET or HEAD.

```text
Method not allowed
```

--------------------------------

### Run All Provider Update Tools

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/cli-tools.md

Demonstrates how to execute all provider update tools individually or by using a task runner like Taskfile.

```bash
# Run all provider update tools
go run ./cmd/openrouter
go run ./cmd/xai
go run ./cmd/huggingface
# ... etc

# Or use the Taskfile
task update-all
```

--------------------------------

### GET /health, GET /healthz

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Simple liveness probe endpoint to check if the service is running.

```APIDOC
## GET /health, GET /healthz

### Description
Simple liveness probe endpoint.

### Method
GET

### Endpoint
/health or /healthz

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8080/health
```

### Response
#### Success Response (200)
- **Body**: `OK`

#### Response Example
```
OK
```
```

--------------------------------

### Create Catwalk Client with Default Configuration

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/configuration.md

Creates a client using default settings, automatically reading the CATWALK_URL from the environment. The default HTTP timeout is 30 seconds.

```go
client := catwalk.New()
```

--------------------------------

### Get Prometheus Metrics

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Exposes Prometheus metrics for monitoring. Use GET method to retrieve metrics in Prometheus text format. Useful for tracking request counts.

```bash
curl http://localhost:8080/metrics | grep catwalk_providers_requests_total
```

--------------------------------

### Fetch All Providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/README.md

Demonstrates the basic usage of the Catwalk client to retrieve a list of all available AI inference providers.

```go
client := catwalk.New()
providers, err := client.GetProviders(context.Background(), "")
```

--------------------------------

### Create New Provider Tool

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/cli-tools.md

This Go program structure is used to create a new CLI tool for integrating an AI provider. It defines how to fetch models, transform them into the Catwalk format, and write the configuration to a JSON file.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "time"
    "charm.land/catwalk/pkg/catwalk"
)

type Model struct {
    // Provider's model struct
}

func fetchModels() ([]Model, error) {
    // Fetch from provider API
}

func toProtoModel(m Model) catwalk.Model {
    // Transform to catwalk format
}

func main() {
    models, err := fetchModels()
    if err != nil {
        log.Fatal(err)
    }
    
    provider := catwalk.Provider{
        Name: "Provider Name",
        ID:   "provider-id",
        // ... fill in details
        Models: make([]catwalk.Model, len(models)),
    }
    
    for i, m := range models {
        provider.Models[i] = toProtoModel(m)
    }
    
    data, _ := json.MarshalIndent(provider, "", "  ")
    if err := os.WriteFile("internal/providers/configs/{provider}.json", data, 0o600); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### GET /healthz

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Alternative liveness probe endpoint, functionally identical to /health.

```APIDOC
## GET /healthz

### Description
Alternative liveness probe endpoint, functionally identical to /health.

### Method
GET

### Endpoint
`http://localhost:8080/healthz`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response (200 OK)
- **Status Code**: 200
- **Content-Type**: `text/plain`
- **Body**: `OK`
```

--------------------------------

### GET /providers (Deprecated)

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Legacy endpoint that redirects users to the new /v2/providers endpoint.

```APIDOC
## GET /providers (Deprecated)

### Description
Legacy endpoint that redirects users to the new /v2/providers endpoint.

### Method
GET

### Endpoint
`http://localhost:8080/providers`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None
```

--------------------------------

### Find Cheapest Model with Requirements

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Identifies the cheapest model that meets a minimum context window size and optionally supports image analysis.

```Go
func cheapestModel(provider *catwalk.Provider, minContext int64, needsImages bool) *catwalk.Model {
    var cheapest *catwalk.Model
    
    for i, m := range provider.Models {
        if m.ContextWindow < minContext {
            continue
        }
        if needsImages && !m.SupportsImages {
            continue
        }
        
        if cheapest == nil || m.CostPer1MIn < cheapest.CostPer1MIn {
            cheapest = &provider.Models[i]
        }
    }
    
    return cheapest
}
```

--------------------------------

### New Catwalk Client with Custom URL

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Instantiate a new catwalk client pointing to a specific server URL.

```go
import (
    "context"
    "charm.land/catwalk/pkg/catwalk"
)

// Create client pointing to specific server
client := catwalk.NewWithURL("http://catwalk-api.example.com:8080")
```

--------------------------------

### Deprecated Providers Endpoint

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

This is a legacy endpoint that now redirects all GET requests to the newer /v2/providers endpoint.

```http
GET http://localhost:8080/providers
```

--------------------------------

### Fetch All Providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Fetches all available providers from the catwalk server and prints their details. Ensure the client is initialized before calling this function.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "charm.land/catwalk/pkg/catwalk"
)

func main() {
    client := catwalk.New()
    
    // Fetch all providers
    providers, err := client.GetProviders(context.Background(), "")
    if err != nil {
        log.Fatal("Failed to fetch providers:", err)
    }
    
    fmt.Printf("Found %d providers\n", len(providers))
    for _, p := range providers {
        fmt.Printf("- %s (%s): %d models\n", p.Name, p.ID, len(p.Models))
    }
}
```

--------------------------------

### New Catwalk Client

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Instantiate a new catwalk client. It uses the CATWALK_URL environment variable by default or falls back to localhost:8080.

```go
import (
    "context"
    "charm.land/catwalk/pkg/catwalk"
)

// Create client using CATWALK_URL env var or localhost:8080
client := catwalk.New()
```

--------------------------------

### Project Structure

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Illustrates the directory layout of the Catwalk project, showing the organization of command-line tools, internal provider logic, and the public API package.

```go
charm.land/catwalk/
├── cmd/                          # Command-line tools for updating providers
│   ├── aihubmix/
│   ├── avian/
│   ├── chutes/
│   ├── copilot/
│   ├── cortecs/
│   ├── huggingface/
│   ├── ionet/
│   ├── nebius/
│   ├── neuralwatt/
│   ├── opencode-go/
│   ├── opencode-zen/
│   ├── openrouter/               # Fetch OpenRouter models
│   ├── pioneer/
│   ├── synthetic/
│   ├── venice/
│   ├── vercel/
│   └── xai/                      # Fetch xAI Grok models
├── internal/
│   └── providers/
│       ├── providers.go          # Provider registry
│       ├── providers_test.go     # Provider validation tests
│       └── configs/              # Provider configuration JSON files
│           ├── aihubmix.json
│           ├── anthropic.json
│           ├── azure.json
│           └── ... (30+ more)
├── pkg/
│   ├── catwalk/                  # Public API package
│   │   ├── client.go             # HTTP client for catwalk service
│   │   ├── provider.go           # Provider and model types
│   │   └── pkg.go                # Package documentation
│   └── embedded/                 # Offline provider access
│       └── embedded.go           # Embedded provider loader
├── main.go                       # HTTP server entry point
├── go.mod
├── go.sum
└── Taskfile.yaml
```

--------------------------------

### GET /providers (Deprecated)

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Legacy endpoint that returns an error message directing clients to the /v2/providers endpoint.

```APIDOC
## GET /providers (Deprecated)

### Description
Legacy endpoint; returns error message directing clients to /v2/providers.

### Method
GET

### Endpoint
/providers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **error** (string) - Message indicating the endpoint is deprecated and to use /v2/providers.

#### Response Example
```json
{
  "error": "This endpoint was removed. Please use /v2/providers instead."
}
```

### Status
200 (for backward compatibility)
```

--------------------------------

### GET /v2/providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Retrieves all available providers in JSON format. Supports ETag caching for efficient client-side caching.

```APIDOC
## GET /v2/providers

### Description
Retrieves all available providers in JSON format with ETag caching support.

### Method
GET or HEAD

### Endpoint
/v2/providers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **name** (string) - The name of the provider.
- **id** (string) - The unique identifier for the provider.
- **type** (string) - The type of the provider.
- **api_key** (string) - The API key for the provider (sensitive).
- **api_endpoint** (string) - The API endpoint for the provider.
- **default_large_model_id** (string) - The default large model ID for the provider.
- **default_small_model_id** (string) - The default small model ID for the provider.
- **models** (array) - A list of available models for the provider.

#### Response Example
```json
[
  {
    "name": "Anthropic",
    "id": "anthropic",
    "type": "anthropic",
    "api_key": "$ANTHROPIC_API_KEY",
    "api_endpoint": "$ANTHROPIC_API_ENDPOINT",
    "default_large_model_id": "claude-sonnet-4-6",
    "default_small_model_id": "claude-haiku-4-5-20251001",
    "models": [
      {
        "id": "claude-sonnet-4-6",
        "name": "Claude Sonnet 4.6",
        "cost_per_1m_in": 3,
        "cost_per_1m_out": 15,
        ...
      }
    ]
  }
]
```

### Headers
- `Content-Type: application/json`
- `ETag` — Hash of response body for conditional requests

### Status Codes
- 200: Success; response body contains provider list
- 304: Not Modified; client's ETag matches server state
- 405: Method not allowed; only GET and HEAD are supported
```

--------------------------------

### catwalk.New

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Creates a new client instance for the catwalk service. It uses the CATWALK_URL environment variable or defaults to localhost:8080.

```APIDOC
## Function: New

### Description
Creates a new client instance using the CATWALK_URL environment variable or localhost:8080 as fallback.

### Signature
```go
func New() *Client
```

### Parameters
None

### Returns
- `*Client` — A new client instance configured with default settings

### Example
```go
client := catwalk.New()
```
```

--------------------------------

### Get Known Inference Providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/types.md

Retrieves a slice of all supported inference provider identifiers. Useful for iterating through available providers.

```go
func KnownProviders() []InferenceProvider
```

```go
for _, provider := range catwalk.KnownProviders() {
    fmt.Println(provider)
}
```

--------------------------------

### Compare Model Input/Output Costs

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Calculates and compares the input, output, and average costs per 1,000 tokens for a list of models. Assumes a ratio for input tokens.

```Go
type ModelCostComparison struct {
    ModelName      string
    InputCost      float64
    OutputCost     float64
    AvgCost        float64
    TotalPer1k     float64 // Average cost per 1000 tokens
}

func compareModelCosts(models []catwalk.Model, avgInputRatio float64) []ModelCostComparison {
    var comparisons []ModelCostComparison
    
    for _, m := range models {
        // Assume typical request is avgInputRatio% input tokens
        avgCost := (m.CostPer1MIn * avgInputRatio) + (m.CostPer1MOut * (1 - avgInputRatio))
        
        comparisons = append(comparisons, ModelCostComparison{
            ModelName:   m.Name,
            InputCost:   m.CostPer1MIn,
            OutputCost:  m.CostPer1MOut,
            AvgCost:     avgCost,
            TotalPer1k:  avgCost / 1000,
        })
    }
    
    return comparisons
}

// Usage: Assume 80% of tokens are input
costs := compareModelCosts(provider.Models, 0.8)
for _, c := range costs {
    fmt.Printf("%s: $%.4f per 1k tokens\n", c.ModelName, c.TotalPer1k)
}
```

--------------------------------

### Run Main HTTP Server

Source: https://github.com/charmbracelet/catwalk/blob/main/CRUSH.md

Build and run the main HTTP server for the Catwalk project. The server will be accessible on port 8080.

```bash
go run .
```

--------------------------------

### Get All Known Provider IDs

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Returns a slice of all recognized InferenceProvider identifiers. This can be used to iterate through or validate provider types.

```go
knownProviders := catwalk.KnownProviders()
```

--------------------------------

### Create Catwalk Client with Explicit URL

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/configuration.md

Creates a client by providing an explicit URL. This overrides any CATWALK_URL environment variable. The default HTTP timeout remains 30 seconds.

```go
client := catwalk.NewWithURL("http://catwalk-server.internal:8080")
```

--------------------------------

### Iterate Provider Options

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Demonstrates how to access and print provider-specific options from the ModelOptions struct. Useful for debugging or custom integrations.

```go
if model.Options.ProviderOptions != nil {
    for key, value := range model.Options.ProviderOptions {
        fmt.Printf("%s: %v\n", key, value)
    }
}
```

--------------------------------

### Create Catwalk Client with Custom URL

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/packages-overview.md

Instantiates the Catwalk HTTP client with a specific service URL. Use this when the Catwalk service is not running on the default address.

```go
c := catwalk.NewWithURL("http://localhost:8080")
```

--------------------------------

### Get All Embedded Providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Retrieves all provider configurations stored locally within the embedded package. Useful for offline access to provider data.

```go
providers := embedded.GetAll()
for _, provider := range providers {
    fmt.Printf("%d models available for %s\n", len(provider.Models), provider.Name)
}
```

--------------------------------

### Fetch All Providers from Catwalk Server

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/providers-list.md

Use this snippet to retrieve all available AI providers from a running catwalk server. It iterates through the fetched providers and prints their names, IDs, types, and the number of models they support.

```go
client := catwalk.NewWithURL("http://localhost:8080")
providers, err := client.GetProviders(context.Background(), "")
if err != nil {
    log.Fatal(err)
}

for _, provider := range providers {
    fmt.Printf("Provider: %s (%s)\n", provider.Name, provider.ID)
    fmt.Printf("  Type: %s\n", provider.Type)
    fmt.Printf("  Models: %d\n", len(provider.Models))
}
```

--------------------------------

### Run xAI Tool

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/cli-tools.md

Execute the xAI tool to fetch Grok models and generate configuration. This updates the `internal/providers/configs/xai.json` file.

```bash
go run ./cmd/xai
```

--------------------------------

### Print Model Capabilities

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Prints detailed information about a model's capabilities, including context window, token limits, image support, reasoning abilities, and pricing. Useful for understanding model constraints and costs.

```go
func printCapabilities(model *catwalk.Model) {
    fmt.Printf("Model: %s\n", model.Name)
    fmt.Printf("  Context: %d tokens\n", model.ContextWindow)
    fmt.Printf("  Max Output: %d tokens\n", model.DefaultMaxTokens)
    fmt.Printf("  Images: %v\n", model.SupportsImages)
    fmt.Printf("  Reasoning: %v\n", model.CanReason)
    
    if model.CanReason {
        fmt.Printf("    Levels: %v\n", model.ReasoningLevels)
        fmt.Printf("    Default: %s\n", model.DefaultReasoningEffort)
    }
    
    fmt.Printf("  Pricing:\n")
    fmt.Printf("    Input: $%.4f/1M\n", model.CostPer1MIn)
    fmt.Printf("    Output: $%.4f/1M\n", model.CostPer1MOut)
    
    if model.CostPer1MInCached > 0 {
        fmt.Printf("    Cached Input: $%.4f/1M\n", model.CostPer1MInCached)
        fmt.Printf("    Cached Output: $%.4f/1M\n", model.CostPer1MOutCached)
    }
}
```

--------------------------------

### Run Provider CLI

Source: https://github.com/charmbracelet/catwalk/blob/main/CRUSH.md

Build and run a command-line interface (CLI) tool to update a specific provider's JSON configuration file. Replace `{provider-name}` with the actual provider's name.

```bash
go run ./cmd/{provider-name}
```

--------------------------------

### ModelOptions Struct Definition

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/types.md

Defines the configuration options for Catwalk models, including parameters for temperature, top-p, top-k, frequency penalty, presence penalty, and provider-specific options.

```go
type ModelOptions struct {
    Temperature      *float64       `json:"temperature,omitempty"`
    TopP             *float64       `json:"top_p,omitempty"`
    TopK             *int64         `json:"top_k,omitempty"`
    FrequencyPenalty *float64       `json:"frequency_penalty,omitempty"`
    PresencePenalty  *float64       `json:"presence_penalty,omitempty"`
    ProviderOptions  map[string]any `json:"provider_options,omitempty"`
}
```

--------------------------------

### Checking for Image Support

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Iterates through a list of models and prints the names of those that support image inputs.

```go
for _, m := range provider.Models {
    if m.SupportsImages {
        fmt.Printf("%s supports images\n", m.Name)
    }
}
```

--------------------------------

### Run All Tests

Source: https://github.com/charmbracelet/catwalk/blob/main/CRUSH.md

Execute all tests within the project. This command ensures that all components are functioning as expected.

```bash
go test ./...
```

--------------------------------

### Load Provider Configuration from JSON

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/configuration.md

This Go function unmarshals JSON data into a catwalk.Provider struct. It logs any unmarshalling errors but continues execution, returning an empty provider on failure. Use this to load provider configurations dynamically.

```go
func loadProviderFromConfig(configData []byte) catwalk.Provider {
    var p catwalk.Provider
    if err := json.Unmarshal(configData, &p); err != nil {
        log.Printf("Error loading provider config: %v", err)
        return catwalk.Provider{}
    }
    return p
}
```

--------------------------------

### Fetch All Providers

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/README.md

Retrieves a list of all available AI providers. This is a fundamental step for discovering and interacting with AI models.

```go
providers, err := client.GetProviders(context.Background(), "")
```

--------------------------------

### Get Providers with ETag Support

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Fetches available providers from the catwalk service. Supports conditional requests using ETags to avoid redundant data transfer. Handles `ErrNotModified` for cached data.

```go
providers, err := client.GetProviders(context.Background(), "")
if err != nil {
    if errors.Is(err, catwalk.ErrNotModified) {
        // Use cached providers
    } else {
        log.Fatal(err)
    }
}

for _, p := range providers {
    fmt.Printf("Provider: %s (%s)\n", p.Name, p.ID)
}
```

--------------------------------

### Set File Permissions in Go

Source: https://github.com/charmbracelet/catwalk/blob/main/CRUSH.md

Use octal literal `0o600` to set file permissions for sensitive configuration files, ensuring only the owner can read and write.

```go
0o600
```

--------------------------------

### Check Generated JSON File

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/cli-tools.md

Uses 'jq' to pretty-print the content of a provider's JSON configuration file. Replace '{provider}' with the specific provider name.

```bash
cat internal/providers/configs/{provider}.json | jq .
```

--------------------------------

### Find Cheapest Provider for Model Class

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Calculates the minimum cost to run a specified number of tokens across available providers and their models. This function iterates through all providers and models to find the most cost-effective option.

```go
import (
    "fmt"
    "charm.land/catwalk/pkg/catwalk"
)

// Find cheapest provider for a specific model class
func cheapestProviderFor(providers []catwalk.Provider, tokens int64) (string, float64) {
    minCost := float64(1<<63 - 1) // max value
    minProvider := ""
    
    for _, p := range providers {
        for _, m := range p.Models {
            cost := estimateCost(&m, tokens, tokens/10, false)
            if cost < minCost {
                minCost = cost
                minProvider = p.Name
            }
        }
    }
    
    return minProvider, minCost
}

// Usage
provider, cost := cheapestProviderFor(providers, 100_000)
fmt.Printf("Cheapest for 100k input: %s ($%.4f)\n", provider, cost)
```

--------------------------------

### catwalk.NewWithURL

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Creates a new client instance for the catwalk service with a specified base URL.

```APIDOC
## Function: NewWithURL

### Description
Creates a new client with a specific base URL for the catwalk service.

### Signature
```go
func NewWithURL(url string) *Client
```

### Parameters
#### Path Parameters
- **url** (string) - Required - Base URL for the catwalk service (e.g., `http://localhost:8080`)

### Returns
- `*Client` — A new client configured with the specified URL

### Example
```go
client := catwalk.NewWithURL("http://catwalk-server:8080")
```
```

--------------------------------

### List All Known Provider IDs

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/providers-list.md

This snippet shows how to iterate over and print all known provider identifiers defined within the catwalk package. It's useful for understanding the available provider IDs.

```go
import "charm.land/catwalk/pkg/catwalk"

for _, providerID := range catwalk.KnownProviders() {
    fmt.Println(providerID)
}
```

--------------------------------

### Find Cheapest Model by Input Cost

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Determines the model with the lowest cost per million input tokens for a given provider. Useful for optimizing cost-sensitive applications.

```go
// Find cheapest model for input tokens
func cheapestModel(provider *catwalk.Provider) *catwalk.Model {
    if len(provider.Models) == 0 {
        return nil
    }
    
    cheapest := &provider.Models[0]
    for i := 1; i < len(provider.Models); i++ {
        if provider.Models[i].CostPer1MIn < cheapest.CostPer1MIn {
            cheapest = &provider.Models[i]
        }
    }
    return cheapest
}

// Usage
cheap := cheapestModel(anthropic)
fmt.Printf("Cheapest model: %s ($%.4f per 1M tokens)\n", cheap.Name, cheap.CostPer1MIn)
```

--------------------------------

### Accessing Model Context Window

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Prints the context window size of a model and filters models with a large context window.

```go
fmt.Printf("Context window: %d tokens\n", model.ContextWindow)

// Find models with large context
largeContext := []catwalk.Model{}
for _, m := range provider.Models {
    if m.ContextWindow >= 100_000 {
        largeContext = append(largeContext, m)
    }
}
```

--------------------------------

### ETag Caching with HTTP API

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/README.md

Demonstrates how to use ETags for efficient caching of provider data. The first request fetches data and its ETag, while subsequent requests use the ETag to check for modifications.

```go
client := catwalk.New()
providers, _ := client.GetProviders(ctx, "")
etag := catwalk.Etag(json.Marshal(providers))

providers, err := client.GetProviders(ctx, etag)
if errors.Is(err, catwalk.ErrNotModified) {
    // Use cached data
}
```

--------------------------------

### Retrieve AI Provider Configurations

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/endpoints.md

Fetches all available AI provider configurations, including their models and capabilities. Supports conditional caching using the If-None-Match header and can also be used with HEAD requests for headers only.

```bash
# Successful request with conditional caching
curl -i -H "If-None-Match: \"abc123\"" http://localhost:8080/v2/providers

# If unchanged, returns 304
# If changed, returns 200 with new ETag header

# HEAD request (headers only)
curl -I http://localhost:8080/v2/providers
```

--------------------------------

### Checking for Cached Input Token Support

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Checks if a model supports prompt caching and calculates the percentage savings on input tokens if caching is enabled.

```go
if model.CostPer1MInCached > 0 {
    fmt.Println("Model supports prompt caching")
    savingsPercent := (1 - model.CostPer1MInCached/model.CostPer1MIn) * 100
    fmt.Printf("Cache saves %.1f%% on input tokens\n", savingsPercent)
}
```

--------------------------------

### Define Model Options Structure

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Defines the structure for model-specific configuration options, including parameters for controlling generation behavior.

```go
type ModelOptions struct {
    Temperature      *float64       // Randomness (0-2)
    TopP             *float64       // Nucleus sampling
    TopK             *int64         // Top-K sampling
    FrequencyPenalty *float64       // Reduce repetition
    PresencePenalty  *float64       // Encourage diversity
    ProviderOptions  map[string]any // Provider-specific
}
```

--------------------------------

### Filter Models Supporting Images

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/README.md

Shows how to filter a list of models to find only those that support image inputs.

```go
// Models that support images
imageModels := []catwalk.Model{}
for _, m := range provider.Models {
    if m.SupportsImages {
        imageModels = append(imageModels, m)
    }
}
```

--------------------------------

### Handle Request Timeout

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Fetches providers with a context that has a timeout. If the request exceeds the specified duration, it logs a timeout error.

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

providers, err := client.GetProviders(ctx, "")
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        log.Fatal("Request timeout after 5 seconds")
    }
    log.Fatal(err)
}
```

--------------------------------

### Checking and Displaying Reasoning Capabilities

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Checks if a model supports reasoning and displays its available reasoning levels and default effort. It also filters a list of models to find those that support reasoning.

```go
// Check if model supports reasoning
if model.CanReason {
    fmt.Printf("Reasoning levels: %v\n", model.ReasoningLevels)
    fmt.Printf("Default effort: %s\n", model.DefaultReasoningEffort)
}

// Find reasoning models
reasoningModels := []catwalk.Model{}
for _, m := range provider.Models {
    if m.CanReason {
        reasoningModels = append(reasoningModels, m)
    }
}
```

--------------------------------

### Client.GetProviders

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/api-reference.md

Retrieves all available providers from the catwalk service. Supports ETag for conditional requests to avoid redundant data transfer.

```APIDOC
## Method: Client.GetProviders

### Description
Retrieves all available providers from the catwalk service with ETag support for conditional requests.

### Signature
```go
func (c *Client) GetProviders(ctx context.Context, etag string) ([]Provider, error)
```

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for request lifecycle management and cancellation
- **etag** (string) - Optional - ETag from a previous request for conditional fetching (returns ErrNotModified if unchanged)

### Returns
- `[]Provider` — Slice of all available providers
- `error` — Error if request fails, or `ErrNotModified` if etag matches server state

### Throws/Rejects
- `ErrNotModified` - Etag matches server state; no new data to download
- Network error - HTTP request fails to complete
- Status 404 or 5xx - Server returns error status code

### Example
```go
providers, err := client.GetProviders(context.Background(), "")
if err != nil {
    if errors.Is(err, catwalk.ErrNotModified) {
        // Use cached providers
    } else {
        log.Fatal(err)
    }
}

for _, p := range providers {
    fmt.Printf("Provider: %s (%s)\n", p.Name, p.ID)
}
```
```

--------------------------------

### Filter Models for Reasoning Tasks

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/model-capabilities.md

Retrieves models capable of reasoning with a context window of at least 64,000 tokens.

```Go
func reasoningModels(provider *catwalk.Provider) []catwalk.Model {
    result := []catwalk.Model{}
    for _, m := range provider.Models {
        if m.CanReason && m.ContextWindow >= 64_000 {
            result = append(result, m)
        }
    }
    return result
}
```

--------------------------------

### Find a Specific Model

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/README.md

Illustrates how to iterate through fetched providers and their models to find a model with a specific ID.

```go
for _, p := range providers {
    for _, m := range p.Models {
        if m.ID == "claude-sonnet-4-6" {
            // Found it
        }
    }
}
```

--------------------------------

### Handle Specific Catwalk Errors

Source: https://github.com/charmbracelet/catwalk/blob/main/_autodocs/client-usage.md

Demonstrates how to check for and handle common errors returned by the Catwalk client, such as `ErrNotModified`, context-related errors like `DeadlineExceeded` and `Canceled`, and generic network issues.

```go
import (
    "context"
    "errors"
    "fmt"
    "log"
    "net/http"
    "charm.land/catwalk/pkg/catwalk"
)

func main() {
    client := catwalk.NewWithURL("http://nonexistent-server:8080")
    
    providers, err := client.GetProviders(context.Background(), "")
    if err != nil {
        // Check for specific errors
        if errors.Is(err, catwalk.ErrNotModified) {
            fmt.Println("Data unchanged; using cached version")
        } else if errors.Is(err, context.DeadlineExceeded) {
            fmt.Println("Request timeout")
        } else if errors.Is(err, context.Canceled) {
            fmt.Println("Request was canceled")
        } else {
            // Generic network or HTTP error
            fmt.Printf("Error: %v\n", err)
        }
        return
    }
    
    fmt.Printf("Got %d providers\n", len(providers))
}
```