### Starting the Server

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/README.md

Examples of how to start the TokenRouter server using the `torod` command-line tool.

```bash
# First-time setup (interactive)
torod serve

# With custom config
torod serve --config /path/to/config.toml

# With overrides
torod serve --listen-addr 0.0.0.0:8080 --allow-localhost-no-auth
```

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

### Quick Start - Start server

Source: https://github.com/lkarlslund/tokenrouter/blob/master/README.md

Command to start the TokenRouter server. If config does not exist, 'serve' launches first-time setup automatically.

```bash
torod serve
```

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

### Example Usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Demonstrates initializing the config store, getting a snapshot, updating configuration, and adding/updating providers.

```go
// Initialize
cfg := config.NewDefaultServerConfig()
store := config.NewServerConfigStore(configPath, cfg)

// Get current config
snap := store.Snapshot()
log.Printf("Listening on %s", snap.ListenAddr)

// Update configuration
err := store.Update(func(cfg *config.ServerConfig) error {
	cfg.ListenAddr = "0.0.0.0:8080"
	cfg.AutoEnablePublicFreeModels = false
	return nil
})

// Add provider
err = store.AddProvider(config.ProviderConfig{
	Name:    "groq",
	BaseURL: "https://api.groq.com",
	APIKey:  "sk-...",
	Enabled: true,
})

// Update specific provider
err = store.UpdateProvider("openai", func(p *config.ProviderConfig) error {
	p.TimeoutSeconds = 60
	return nil
})
```

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

### Install toro (Client)

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Installs the latest version of the TokenRouter client CLI using go install.

```bash
go install github.com/lkarlslund/tokenrouter/cmd/toro@latest
```

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

### List Method Example: Get all entries

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of retrieving all log entries from the store by setting the limit to 0.

```go
// Get all entries
entries = store.List(logstore.ListFilter{
	Limit: 0, // 0 = unlimited
})
```

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

### Opencode example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of launching OpenCode with a custom name and TTL.

```bash
toro opencode --name "OpenCode session" --ttl 6h
```

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

### NewServer Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example of how to create a new Server instance.

```go
cfg := config.NewDefaultServerConfig()
srv, err := proxy.NewServer("/etc/tokenrouter/torod.toml", cfg)
if err != nil {
	log.Fatalf("Failed to create server: %v", err)
}
```

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

### hostIsLoopback Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example demonstrating the usage of hostIsLoopback.

```go
if hostIsLoopback("127.0.0.1") {
	// Is loopback
}
```

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

### SetProviders Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of setting providers and enabling background refresh.

```go
allProviders := configStore.Snapshot().Providers
pricingMgr.SetProviders(allProviders)
// Refresh will now run automatically in background
```

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

### Example Usage: Resolve Auth Identity

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example demonstrating the use of `resolveAuthIdentity` to get user identity and check for admin privileges.

```go
identity, ok := resolveAuthIdentity(token, cfg)
if !ok {
	return fmt.Errorf("invalid token")
}
if !identity.IsAdmin {
	return fmt.Errorf("admin required")
}
```

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

### handleV1Root Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example curl command to access the GET /v1 endpoint.

```bash
curl http://127.0.0.1:7050/v1 \
  -H "Authorization: Bearer sk-..."
```

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

### Install - From source

Source: https://github.com/lkarlslund/tokenrouter/blob/master/README.md

Commands to install TokenRouter binaries from source.

```bash
go install github.com/lkarlslund/tokenrouter/cmd/torod@latest
go install github.com/lkarlslund/tokenrouter/cmd/toro@latest
```

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

### splitModelPrefix Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Examples demonstrating the usage of splitModelPrefix.

```Go
provider, model, hasSplit := splitModelPrefix("openai/gpt-4o")
// provider = "openai", model = "gpt-4o", hasSplit = true

provider, model, hasSplit := splitModelPrefix("gpt-4o")
// provider = "", model = "gpt-4o", hasSplit = false
```

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

### handleModels Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example curl command to access the GET /v1/models endpoint.

```bash
curl http://127.0.0.1:7050/v1/models \
  -H "Authorization: Bearer sk-..."
```

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

### Client Configuration Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example TOML configuration for the client.

```toml
server_url = "http://127.0.0.1:7050/v1"
api_key = "sk-..."
```

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

### torod Full Startup Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of a full startup command for the torod server with multiple flags.

```bash
torod \
  --loglevel info \
  serve \
  --config ~/.config/tokenrouter/torod.toml \
  --listen-addr 127.0.0.1:7050 \
  --allow-localhost-no-auth
```

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

### AddProvider Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Example of adding a new provider to the configuration.

```go
provider := config.ProviderConfig{
	Name:        "new-provider",
	BaseURL:     "https://api.example.com",
	APIKey:      "sk-...",
	Enabled:     true,
	TimeoutSeconds: 30,
}
if err := store.AddProvider(provider); err != nil {
	log.Fatalf("Failed to add provider: %v", err)
}
```

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

### Run Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example of how to run the server with context cancellation for graceful shutdown.

```go
ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGTERM)
def cancel()

if err := srv.Run(ctx); err != nil {
	log.Printf("Server error: %v", err)
}
```

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

### Install torod (Server)

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Installs the latest version of the TokenRouter daemon server using go install.

```bash
go install github.com/lkarlslund/tokenrouter/cmd/torod@latest
```

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

### NewServerConfigStore Constructor Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Example of creating a new ServerConfigStore instance.

```go
cfg := config.NewDefaultServerConfig()
store := config.NewServerConfigStore("/etc/tokenrouter/torod.toml", cfg)
```

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

### Snapshot Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Example of retrieving a configuration snapshot and logging provider information.

```go
cfg := store.Snapshot()
log.Printf("Providers: %d", len(cfg.Providers))
for _, p := range cfg.Providers {
	if p.Enabled {
		log.Printf("  - %s (%s)", p.Name, p.BaseURL)
	}
}
```

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

### GetPricing Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of retrieving and displaying pricing for a model.

```go
pricing := pricingMgr.GetPricing("openai", "gpt-4o")
if pricing != nil {
	log.Printf("GPT-4o: $%.4f/1M input, $%.4f/1M output",
					pricing.InputPer1M, pricing.OutputPer1M)
} else {
	log.Printf("Pricing not available")
}
```

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

### AllPricing Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of retrieving and logging the count of cached pricing entries.

```go
allPricing := pricingMgr.AllPricing()
log.Printf("Cached pricing for %d models", len(allPricing))
```

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

### toro set-key Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of setting a specific API key.

```bash
toro set-key sk-my-secret-key-123
```

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

### toro status --json Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of getting the status output in JSON format.

```bash
toro status --json | jq .
```

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

### Start Benchmark Request Body

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON request body for starting a benchmark run.

```json
{"chats_per_model": 5, "messages_per_chat": 3, "stop_after_tokens": 10000}
```

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

### Run Method

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Starts the server and blocks until context is cancelled or an error occurs. Handles HTTP and HTTPS listeners, graceful shutdown, TLS setup, and background maintenance tasks.

```go
func (s *Server) Run(ctx context.Context) error
```

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

### Example Usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Demonstrates how to create, configure, refresh, and query the Pricing Manager.

```go
// Create manager
pricingMgr, err := pricing.NewManager(config.DefaultPricingCachePath())
if err != nil {
	log.Fatalf("Failed to create pricing manager: %v", err)
}
def pricingMgr.Stop()

// Set providers to enable refresh
providers := configStore.Snapshot().Providers
pricingMgr.SetProviders(providers)

// Force immediate refresh
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
err = pricingMgr.Refresh(ctx)
cancel()
if err != nil {
	log.Printf("Pricing refresh failed: %v", err)
}

// Get pricing for a model
pricing := pricingMgr.GetPricing("openai", "gpt-4o")
if pricing != nil {
	log.Printf("GPT-4o input: $%.4f/1M", pricing.InputPer1M)
	log.Printf("GPT-4o output: $%.4f/1M", pricing.OutputPer1M)
	log.Printf("Currency: %s", pricing.Currency)
	log.Printf("Source: %s", pricing.Source)
	log.Printf("Discovered: %s", pricing.DiscoveredAt.Format(time.RFC3339))
}

// List all pricing
allPricing := pricingMgr.AllPricing()
log.Printf("Total models with pricing: %d", len(allPricing))

// Group by provider
byProvider := make(map[string]int)
for _, p := range allPricing {
	byProvider[p.Provider]++
}
for provider, count := range byProvider {
	log.Printf("  %s: %d models", provider, count)
}
```

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

### Wrap example with npm test

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of using the wrap command to run an npm test command.

```bash
toro wrap --name "Test run" -- npm test
```

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

### Example Usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/conversations-store.md

Demonstrates how to create, record, list, get, delete, and clear conversations using the store.

```go
// Create store
store := conversations.NewStore(
	config.DefaultConversationsPath(),
	conversations.Settings{
		Enabled:    true,
		MaxItems:   5000,
		MaxAgeDays: 30,
	},
)
defer store.Flush()

// Record an exchange
rec, ok := store.Add(conversations.CaptureInput{
	Timestamp:           time.Now(),
	Endpoint:            "/v1/chat/completions",
	Provider:            "openai",
	Model:               "gpt-4o",
	RemoteIP:            "192.168.1.1",
	APIKeyName:          "Main Key",
	RequestPayload:      chatRequest,
	ResponsePayload:     chatResponse,
	RequestTextMarkdown: "User: What is AI?",
	ResponseTextMarkdown: "Assistant: AI is...",
	StatusCode:          200,
	LatencyMS:           500,
})

// List conversations
threads := store.List(conversations.ListFilter{
	Query:      "AI",
	Provider:   "openai",
	Limit:      20,
})

// Get full conversation
if len(threads) > 0 {
	records, _ := store.GetConversation(threads[0].ConversationKey)
	log.Printf("Conversation: %d exchanges", len(records))
}

// Delete old conversation
store.Delete("conv-old")

// Clear all
store.Clear()
```

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

### Codex example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of launching Codex with a custom name and TTL.

```bash
toro codex --name "My coding session" --ttl 4h
```

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

### Provider Resolver Example Usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Example demonstrating how to use the ProviderResolver.

```Go
// Create resolver
resolver := proxy.NewProviderResolver(configStore)

// List all available providers
providers := resolver.ListProviders()
log.Printf("Available providers: %d", len(providers))
for _, p := range providers {
	log.Printf("  - %s (%s)", p.Name, p.BaseURL)
}

// Discover all models
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

models, err := resolver.DiscoverModels(ctx)
if err != nil {
	log.Printf("Discovery error: %v", err)
}
log.Printf("Available models: %d", len(models))

// Route specific model
provider, upstreamModel, err := resolver.ResolveModel("openai/gpt-4o")
if err != nil {
	log.Fatalf("Cannot resolve model: %v", err)
}
log.Printf("Route to %s: %s", provider.Name, upstreamModel)

// Look up provider
openai := resolver.ResolveProvider("openai")
if openai != nil {
	log.Printf("OpenAI: %s (enabled=%v)", openai.BaseURL, openai.Enabled)
}
```

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

### List Method Example: Get recent errors

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of listing the most recent 100 error entries from the log store.

```go
// Get recent errors
entries := store.List(logstore.ListFilter{
	Level: "error",
	Limit: 100,
})
for _, entry := range entries {
	log.Printf("[%s] %s: %s", entry.Timestamp.Format(time.RFC3339), entry.Level, entry.Message)
}
```

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

### toro --config Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of specifying a client configuration file for the toro command.

```bash
toro --config ~/.config/tokenrouter/toro.toml status
```

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

### Refresh Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of forcing a synchronous pricing refresh with a timeout.

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

if err := pricingMgr.Refresh(ctx); err != nil {
	log.Printf("Pricing refresh failed: %v", err)
} else {
	log.Printf("Pricing updated")
}
```

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

### torod --config Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of specifying a configuration file for the torod serve command.

```bash
torod serve --config /etc/tokenrouter/torod.toml
```

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

### normalizeModelID Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Example demonstrating the usage of normalizeModelID.

```Go
normalized := normalizeModelID("gpt-4o:vision")
```

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

### EnsureFreshAsync Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of ensuring pricing is reasonably current using EnsureFreshAsync.

```go
// Ensure pricing is reasonably current
pricingMgr.EnsureFreshAsync()
```

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

### toro --loglevel Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of setting the log level for the toro client.

```bash
toro --loglevel debug status
```

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

### Wrap example with Python script

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of using the wrap command to run a Python script with temporary TokenRouter credentials.

```bash
toro wrap --name "Script run" --ttl 2h -- python my_script.py --input data.json
```

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

### toro connect --server-config Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of using --server-config flag with toro connect to read server defaults.

```bash
toro connect --server-config /etc/tokenrouter/torod.toml
```

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

### NewManager Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of how to create a new pricing manager.

```go
pricingMgr, err := pricing.NewManager(config.DefaultPricingCachePath())
if err != nil {
	log.Fatalf("Failed to create pricing manager: %v", err)
}
```

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

### UpdateProvider Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Example of updating an existing provider's configuration.

```go
err := store.UpdateProvider("openai", func(p *config.ProviderConfig) error {
	p.APIKey = "sk-new-key"
	p.Enabled = true
	return nil
})

```

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

### Quick Start - Configure server

Source: https://github.com/lkarlslund/tokenrouter/blob/master/README.md

Command to configure the TokenRouter server.

```bash
torod config
```

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

### NewStatsStore Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/stats-store.md

Example usage of the NewStatsStore constructor.

```go
stats := proxy.NewStatsStore(0)
```

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

### Add Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/stats-store.md

Example of creating and adding a UsageEvent to the StatsStore.

```go
event := proxy.UsageEvent{
	Timestamp:      time.Now(),
	Provider:       "openai",
	Model:          "gpt-4o",
	ClientIP:       "192.168.1.100",
	APIKeyName:     "Main API Key",
	StatusCode:     200,
	PromptTokens:   10,
	CompletionToks: 25,
	TotalTokens:    35,
	LatencyMS:      450,
	PromptTPS:      15.5,
	GenTPS:         10.2,
}
stats.Add(event)
```

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

### Example Usage: Resolve Incoming Token

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example illustrating how to use `resolveIncomingToken` to find and validate an API key.

```go
tok, ok := resolveIncomingToken(apiKey, cfg.IncomingTokens)
if !ok {
	http.Error(w, "Invalid token", http.StatusUnauthorized)
	return
}
log.Printf("Token: %s, Role: %s", tok.Name, tok.Role)
```

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

### Writer Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of using `logutil.SetOutputTee` with `store.Writer()` to capture all logs into the store.

```go
logutil.SetOutputTee(store.Writer())
// Now all logs are captured to store
```

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

### toro --ttl Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of setting the time-to-live for temporary tokens with wrapper commands.

```bash
toro --ttl 2h opencode
```

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

### remoteHost Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example of how to use the remoteHost function to log the request source.

```go
host := remoteHost(r)
log.Printf("Request from: %s", host)
```

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

### NewStore Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/conversations-store.md

Example of creating a new conversation store with a specified path and settings.

```go
store := conversations.NewStore(
	"/var/cache/tokenrouter/conversations.json",
	conversations.Settings{
		Enabled:    true,
		MaxItems:   5000,
		MaxAgeDays: 30,
	},
)
```

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

### torod --loglevel Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of setting the log level for the torod server.

```bash
torod serve --loglevel debug
```

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

### Example Usage: Key Allowed Check

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example showing how to use `keyAllowed` to check if a token is authorized against server configuration.

```go
cfg := server.store.Snapshot()
if !keyAllowed(token, cfg.IncomingTokens) {
	http.Error(w, "Unauthorized", http.StatusUnauthorized)
	return
}
```

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

### torod --listen-addr Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of overriding the server listening address.

```bash
torod serve --listen-addr 0.0.0.0:8080
```

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

### Example Server Configuration

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/configuration.md

An example TOML configuration file for the TokenRouter server, demonstrating various settings for listening addresses, authentication, model providers, token management, and logging.

```toml
listen_addr = "127.0.0.1:7050"
http_mode = "enabled"
allow_localhost_no_auth = true
auto_enable_public_free_models = true
auto_detect_local_servers = true
auto_remove_expired_tokens = true
default_provider = "openai"

[[incoming_tokens]]
id = "admin-token-1"
name = "Admin Token"
role = "admin"
key = "sk-admin-secret-key"
expires_at = "2025-12-31T23:59:59Z"

[[incoming_tokens]]
id = "user-token-1"
name = "User Token"
role = "inferrer"
key = "sk-user-secret-key"
[incoming_tokens.quota]
[incoming_tokens.quota.requests]
limit = 1000
interval_seconds = 3600
[incoming_tokens.quota.tokens]
limit = 1000000
interval_seconds = 86400

[[providers]]
name = "openai"
provider_type = "openai"
base_url = "https://api.openai.com"
api_key = "sk-..."
enabled = true
timeout_seconds = 30

[[providers]]
name = "ollama"
base_url = "http://localhost:11434"
enabled = true
timeout_seconds = 120

[conversations]
enabled = true
max_items = 5000
max_age_days = 30

[logs]
max_lines = 5000

[tls]
enabled = false
mode = "letsencrypt"
domain = "tokenrouter.example.com"
email = "admin@example.com"

```

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

### Example Usage: Bearer Token Extraction

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example demonstrating how to extract a token using `bearerToken` and handle missing tokens.

```go
token := bearerToken(r.Header)
if token == "" {
	http.Error(w, "Missing token", http.StatusUnauthorized)
	return
}
```

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

### torod --auto-enable-public-free-models Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of enabling auto-discovery of free public models.

```bash
torod serve --auto-enable-public-free-models
```

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

### Pingpong example with multiple flags

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

An example demonstrating the use of multiple flags for the pingpong command.

```bash
toro pingpong \
  --models gpt-4o,claude-3-opus \
  --turn-pairs 5 \
  --starter "What is AI?" \
  --max-tokens 5000
```

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

### Update Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Example of atomically updating the configuration, specifically enabling and updating an API key for a provider.

```go
err := store.Update(func(cfg *config.ServerConfig) error {
	// Find and update a provider
	for i, p := range cfg.Providers {
		if p.Name == "openai" {
			cfg.Providers[i].Enabled = true
			cfg.Providers[i].APIKey = "sk-new-key"
			break
		}
	}
	return nil
})
if err != nil {
	log.Fatalf("Failed to update config: %v", err)
}
```

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

### Example Usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Demonstrates how to use the Log Store API for creating, adding, listing, and managing logs.

```go
// Create store
store := logstore.NewStore(
	config.DefaultLogsPath(),
	logstore.Settings{
		MaxLines: 5000,
	},
)
defer store.Flush()

// Set up callback for real-time notifications
store.SetOnAppend(func() {
	// Notify admin panel
})

// Log some messages
store.Add("info", "Server started", time.Now())
store.Add("info", "Provider discovered: openai", time.Now())
store.Add("warn", "Provider quota running low", time.Now())
store.Add("error", "Request to provider failed", time.Now())

// Get recent errors
errors := store.List(logstore.ListFilter{
	Level: "error",
	Limit: 50,
})
log.Printf("Recent errors: %d", len(errors))

// Search logs
results := store.List(logstore.ListFilter{
	Query: "provider",
	Limit: 100,
})
log.Printf("Logs matching 'provider': %d", len(results))

// Get all entries
all := store.List(logstore.ListFilter{
	Limit: 0,
})
log.Printf("Total logs: %d", len(all))

// Display logs
for _, entry := range all {
	fmt.Printf("[%s] %-5s %s\n",
		entry.Timestamp.Format("15:04:05"),
		entry.Level,
		entry.Message,
	)
}

// Update settings
store.UpdateSettings(logstore.Settings{
	MaxLines: 10000,
})

// Clear all logs
store.Clear()
```

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

### RemoveProvider Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Example of removing a provider from the configuration by its name.

```go
if err := store.RemoveProvider("old-provider"); err != nil {
	log.Fatalf("Failed to remove provider: %v", err)
}
```

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

### Summary Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/stats-store.md

Example of retrieving and logging summary statistics for the last hour, including breakdowns by provider and model.

```go
// Last hour stats
summary := stats.Summary(1 * time.Hour)
log.Printf("Requests: %d", summary.Requests)
log.Printf("Total tokens: %d", summary.TotalTokens)
log.Printf("Avg latency: %.1f ms", summary.AvgLatencyMS)

// Breakdown by provider
for provider, count := range summary.RequestsPerProvider {
	log.Printf("  %s: %d requests", provider, count)
}

// Breakdown by model
for model, count := range summary.RequestsPerModel {
	log.Printf("  %s: %d requests", model, count)
}
```

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

### UpdateSettings Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of updating the log store settings to increase the maximum number of lines to 10000.

```go
store.UpdateSettings(logstore.Settings{
	MaxLines: 10000,
})
```

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

### torod --allow-localhost-no-auth Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of disabling authentication for localhost requests.

```bash
torod serve --allow-localhost-no-auth
```

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

### NewStore Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of creating a new log store with a specified file path and maximum line count for retention.

```go
store := logstore.NewStore(
	"/var/cache/tokenrouter/logs.json",
	logstore.Settings{
		MaxLines: 5000,
	},
)
def store.Flush()
```

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

### Add Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/conversations-store.md

Example of adding a captured API request/response exchange to the conversation store.

```go
rec, ok := store.Add(conversations.CaptureInput{
	Timestamp:            time.Now(),
	Endpoint:             "/v1/chat/completions",
	Provider:             "openai",
	Model:                "gpt-4o",
	RemoteIP:             "192.168.1.100",
	APIKeyName:           "Main Key",
	RequestPayload:       requestBody,
	ResponsePayload:      responseBody,
	RequestTextMarkdown:  "User: Hello",
	ResponseTextMarkdown: "Assistant: Hi there!",
	StatusCode:           200,
	LatencyMS:            450,
	Stream:               false,
})
if ok {
	log.Printf("Recorded conversation: %s", rec.ConversationKey)
}
```

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

### torod config Command Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of using the torod config command to show configuration location.

```bash
torod config
# Output: Configuration location: ~/.config/tokenrouter/torod.toml
```

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

### Flush Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example demonstrating the use of `defer store.Flush()` to ensure logs are persisted when the function exits.

```go
defer store.Flush()

// ... run server ...
```

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

### toro --name Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of setting a display name for temporary tokens with wrapper commands.

```bash
toro --name "Codex Session" codex
```

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

### SetOnAppend Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of setting an on-append callback to notify an admin panel about new log entries.

```go
store.SetOnAppend(func() {
	// Notify admin panel of new logs
	adminHandler.NotifyLogChanged()
})
```

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

### Stop Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Example of stopping the pricing manager's background refresh loop.

```go
defer pricingMgr.Stop()

// Run server...
```

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

### Example Usage: Attach Identity to Context

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example showing how to attach an authentication identity to a request context using `withAPIAuthIdentity`.

```go
ctx = withAPIAuthIdentity(ctx, identity)
newReq := r.WithContext(ctx)
```

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

### Example Usage of DiscoverModels

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Demonstrates how to call DiscoverModels with a context and process the returned models or errors.

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

models, err := resolver.DiscoverModels(ctx)
if err != nil {
	log.Printf("Some providers failed: %v", err)
}

for _, model := range models {
	log.Printf("Model: %s from %s", model.ID, model.Provider)
}
```

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

### GetConversation Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/conversations-store.md

Example of retrieving a specific conversation thread and logging details about its records.

```go
records, ok := store.GetConversation("conv-abc123")
if ok {
	log.Printf("Conversation has %d exchanges", len(records))
	for _, rec := range records {
		log.Printf("  %s: %dms latency", rec.CreatedAt.Format(time.RFC3339), rec.LatencyMS)
	}
}
```

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

### Environment Variable Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of using the TOKENROUTER_CONFIG environment variable to override the default config path.

```bash
export TOKENROUTER_CONFIG=/custom/path/config.toml
torod serve
```

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

### handleStatus Example Request

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example cURL command to fetch server status with a custom period.

```bash
curl http://127.0.0.1:7050/v1/status?period_seconds=86400 \
  -H "Authorization: Bearer sk-..."
```

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

### Example Usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/stats-store.md

Demonstrates how to create, add events to, and retrieve summaries from the persistent stats store.

```go
// Create persistent stats store
stats := proxy.NewPersistentStatsStore(0, config.DefaultUsageStatsPath())
defers stats.Flush()

// Record events
for i := 0; i < 100; i++ {
	event := proxy.UsageEvent{
		Timestamp:      time.Now(),
		Provider:       "openai",
		Model:          "gpt-4o",
		StatusCode:     200,
		PromptTokens:   10,
		CompletionToks: 20,
		TotalTokens:    30,
		LatencyMS:      int64(rand.Intn(1000)),
		PromptTPS:      10.5,
		GenTPS:         5.2,
	}
	stats.Add(event)
}

// Get summary for last hour
summary := stats.Summary(1 * time.Hour)

// Display stats
log.Printf("Period: %d seconds", summary.PeriodSeconds)
log.Printf("Requests: %d", summary.Requests)
log.Printf("Total tokens: %d", summary.TotalTokens)
log.Printf("Avg latency: %.1f ms", summary.AvgLatencyMS)
log.Printf("Avg generation: %.1f tokens/sec", summary.AvgGenerationTPS)

// Analysis by provider
for provider, count := range summary.RequestsPerProvider {
	log.Printf("Provider %s: %d requests", provider, count)
}

// Analysis by model
for model, count := range summary.RequestsPerModel {
	log.Printf("Model %s: %d requests", model, count)
}

// Analysis by token/key
for keyName, count := range summary.RequestsPerAPIKeyName {
	log.Printf("Key %s: %d requests", keyName, count)
}

// Time-series data
for _, bucket := range summary.Buckets {
	log.Printf("%s: %d requests, %d tokens",
		bucket.StartAt.Format(time.RFC3339),
		bucket.Requests,
		bucket.TotalTokens,
	)
}
```

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

### Clear Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of clearing all logs from the store and logging a confirmation message.

```go
store.Clear()
log.Printf("Logs cleared")
```

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

### List Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/conversations-store.md

Example of listing conversation threads with specific filters and displaying thread summaries.

```go
threads := store.List(conversations.ListFilter{
	Query:      "weather",
	Provider:   "openai",
	Limit:      10,
})
for _, thread := range threads {
	log.Printf("Thread %s: %d messages", thread.ConversationKey, thread.Count)
	log.Printf("  Last: %s", thread.LastAt.Format(time.RFC3339))
	log.Printf("  Preview: %s", thread.LastPreview)
}
```

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

### Flush Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/stats-store.md

Example of using defer to ensure the Flush method is called upon process exit.

```go
defer stats.Flush()

// ... run server ...
```

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

### Error Handling Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Example of handling errors by redirecting stderr and checking the exit code.

```bash
toro status 2>/dev/null || echo "Failed to connect"
```

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

### Example Usage: Retrieve Identity from Context

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example demonstrating how to retrieve an authentication identity from a request context using `apiAuthIdentityFromContext`.

```go
identity, ok := apiAuthIdentityFromContext(r.Context())
if !ok {
	http.Error(w, "Not authenticated", http.StatusUnauthorized)
	return
}
```

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

### Get Server Logs Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON response for retrieving server logs.

```json
[{"id": "log-1", "timestamp": "2025-05-25T12:00:00Z", "level": "info", "message": "Log message"}]
```

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

### NewPersistentStatsStore Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/stats-store.md

Example usage of the NewPersistentStatsStore constructor, including deferring a Flush operation.

```go
stats := proxy.NewPersistentStatsStore(0, "/var/cache/tokenrouter/usage")
defers stats.Flush()
```

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

### Get Server Version Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON response for retrieving server version information.

```json
{"version": "v1.2.3", "commit": "abc1234def5678", "date": "2025-05-25T10:30:00Z", "dirty": false}
```

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

### proxyHandler Example Request

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example cURL command for a chat completions request to the /v1/chat/completions endpoint.

```bash
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

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

### Get Single Conversation Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON response for retrieving a single conversation with full details.

```json
{"id": "conv-123", "title": "Conversation", "records": [{"id": "rec-1", "conversation_key": "conv-123", "created_at": "2025-05-25T12:00:00Z", "endpoint": "/v1/chat/completions", "provider": "openai", "model": "gpt-4o", "status_code": 200, "latency_ms": 450}]}
```

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

### List Method Example: Search for specific text

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Example of searching for log entries containing the text 'provider' and limiting the results to 50.

```go
// Search for specific text
entries = store.List(logstore.ListFilter{
	Query: "provider",
	Limit: 50,
})
```

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

### Development session with Codex

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Starts a development session with a specified model and time-to-live.

```bash
toro codex \
  --name "Development session" \
  --ttl 8h \
  --model gpt-4o
```

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

### 502 Bad Gateway Example Scenario

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/errors.md

A cURL command example demonstrating a 502 Bad Gateway error when an OpenAI API key is invalid.

```bash
// OpenAI API key invalid
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hi"}]}'
// Server tries OpenAI, gets 401 from OpenAI
// Returns: HTTP 502 Bad Gateway: provider openai returned 401
```

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

### Status Endpoint Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON response for the GET /v1/status endpoint, showing server health and usage statistics.

```json
{
  "checked_at": "2025-05-25T12:00:00Z",
  "period_seconds": 3600,
  "version": "v1.2.3+abc1234",
  "raw": "v1.2.3",
  "commit": "abc1234def5678",
  "date": "2025-05-25T10:30:00Z",
  "dirty": false,
  "providers_available": 3,
  "providers_online": 3,
  "provider_quotas": {
    "openai": {
      "provider": "openai",
      "status": "ok",
      "left_percent": 45.0,
      "reset_at": "2025-06-01T00:00:00Z"
    }
  },
  "requests": 1234,
  "prompt_tokens": 50000,
  "completion_tokens": 10000,
  "total_tokens": 60000,
  "avg_latency_ms": 450.5,
  "avg_prompt_tps": 120.5,
  "avg_generation_tps": 25.3
}
```

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

### handleV1Root Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example JSON response for the GET /v1 endpoint, indicating available endpoints and service information.

```json
{
  "object": "tokenrouter",
  "service": "TokenRouter OpenAI-compatible API",
  "paths": ["/v1/models", "/v1/chat/completions", "/v1/completions", "/v1/embeddings", "/v1/responses", "/v1/status"]
}
```

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

### handleModels Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Example JSON response for the GET /v1/models endpoint, showing an aggregated list of models from enabled providers.

```json
{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-4o",
      "object": "model",
      "provider": "openai"
    },
    {
      "id": "anthropic/claude-3-opus",
      "object": "model",
      "provider": "anthropic"
    }
  ]
}
```

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

### Example Usage of ResolveProvider

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Shows how to use ResolveProvider to find a specific provider and log its details or a not-found message.

```go
if provider := resolver.ResolveProvider("openai"); provider != nil {
	log.Printf("OpenAI: %s", provider.BaseURL)
} else {
	log.Printf("OpenAI provider not found")
}
```

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

### 402 Payment Required Example Scenario

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/errors.md

A cURL command example that triggers a 402 Payment Required error due to exhausted request quota.

```bash
// Token with 10 requests/hour, already used 10
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer limited-token" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'
// Returns 402 with quota details
```

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

### SetProviders Method Signature

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/pricing-manager.md

Sets the list of providers and starts the background refresh loop.

```go
func (m *Manager) SetProviders(providers []config.ProviderConfig)
```

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

### toro connect Command

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Command to initiate interactive setup for connecting to a TokenRouter server.

```bash
toro connect [flags]
```

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

### Example Usage of ListProviders

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Iterates through the list of providers returned by ListProviders and logs their names and base URLs.

```go
providers := resolver.ListProviders()
for _, p := range providers {
	log.Printf("Provider: %s (%s)", p.Name, p.BaseURL)
	if p.Enabled {
		log.Printf("  Status: enabled")
	}
}
```

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

### Auth API Middleware

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example middleware integration for API authentication.

```go
func (s *Server) authAPIMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		token := bearerToken(r.Header)
		if token == "" && !requestIsTrustedNoAuth(r, s.store.Snapshot()) {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		var identity tokenAuthIdentity
		if token != "" {
			var ok bool
			identity, ok = resolveAuthIdentity(token, s.store.Snapshot())
			if !ok {
				http.Error(w, "unauthorized", http.StatusUnauthorized)
				return
			}
		}
		ctx := withAPIAuthIdentity(r.Context(), identity)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}
```

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

### 401 Unauthorized Example Scenarios

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/errors.md

Examples of cURL commands that would result in a 401 Unauthorized error due to missing, invalid, or expired tokens.

```bash
// Missing token
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'
// Returns 401

// Invalid token
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer invalid-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'
// Returns 401

// Expired token
// Token with expires_at in past
// Returns 401
```

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

### Add Method Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/log-store.md

Demonstrates adding various log entries with different levels and messages to the store.

```go
store.Add("info", "Server started", time.Now())
store.Add("error", "Provider connection failed", time.Now())
store.Add("debug", "Request from 192.168.1.1", time.Now())
```

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

### TokenRouter Server Configuration

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/README.md

Example configuration file for the TokenRouter server (torod.toml).

```toml
listen_addr = "127.0.0.1:7050"
allow_localhost_no_auth = true
auto_enable_public_free_models = true

[[incoming_tokens]]
id = "admin-1"
name = "Admin Token"
role = "admin"
key = "sk-admin-..."

[[providers]]
name = "openai"
base_url = "https://api.openai.com"
api_key = "sk-..."
enabled = true
```

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

### Using the TokenRouter API

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/README.md

Examples of interacting with the TokenRouter API using curl.

```bash
# Get server status
curl http://127.0.0.1:7050/v1/status \
  -H "Authorization: Bearer sk-..."

# List models
curl http://127.0.0.1:7050/v1/models \
  -H "Authorization: Bearer sk-..."

# Chat completion (OpenAI compatible)
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{ "model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello"}] }'
```

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

### Pingpong with custom starter question

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Provides a custom opening question for the pingpong conversation.

```bash
toro pingpong --models gpt-4o,claude-3-opus --starter "Explain quantum computing"
```

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

### Get server status with JSON output

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Retrieves the server status and filters for the number of online providers.

```bash
toro status --json | jq '.providers_online'
# Output: 3
```

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

### Opencode command basic usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Launches OpenCode with a temporary TokenRouter key.

```bash
toro opencode [wrapper_flags] [opencode_args...]
```

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

### requestIsTrustedNoAuth Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/auth.md

Example usage of requestIsTrustedNoAuth to conditionally allow requests without authentication.

```go
if requestIsTrustedNoAuth(r, cfg) {
	// Allow without auth
	return
}
// Require authentication
```

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

### Use One Endpoint Everywhere - Example request

Source: https://github.com/lkarlslund/tokenrouter/blob/master/README.md

Example JSON payload for routing directly to a provider/model.

```json
{
  "model": "groq/llama-3.3-70b-versatile",
  "messages": [{"role": "user", "content": "Hello"}]
}
```

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

### List available models

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Command to list available models from the server.

```bash
toro models [flags]
```

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

### NewServer Constructor

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/server.md

Creates a new Server instance with the given configuration.

```go
func NewServer(configPath string, cfg *config.ServerConfig) (*Server, error)
```

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

### Run test suite with temporary credentials

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Wraps a command (e.g., npm test) with a temporary name and time-to-live for credentials.

```bash
toro wrap \
  --name "CI test run" \
  --ttl 1h \
  -- npm test
```

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

### 400 Bad Request - Invalid Model ID Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/errors.md

Example of a request with an invalid model ID format.

```bash
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"!!!invalid!!!","messages":[{"role":"user","content":"Hi"}]}'
# Returns: HTTP 400 Bad Request or 502 Bad Gateway
```

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

### 400 Bad Request - Missing Required Field Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/errors.md

Example of a request missing the required 'messages' field.

```bash
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o"}'
# Returns: HTTP 400 Bad Request: messages required
```

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

### 400 Bad Request - Invalid JSON Example

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/errors.md

Example of sending invalid JSON in a request to the chat completions endpoint.

```bash
curl http://127.0.0.1:7050/v1/chat/completions \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{invalid json'
# Returns: HTTP 400 Bad Request: invalid character
```

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

### LoadServerConfig

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Loads configuration from TOML file.

```go
func LoadServerConfig(path string) (*ServerConfig, error)
```

```go
cfg, err := config.LoadServerConfig("/etc/tokenrouter/torod.toml")
if err != nil {
	log.Fatalf("Failed to load config: %v", err)
}
```

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

### NewDefaultServerConfig

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Returns default server configuration.

```go
func NewDefaultServerConfig() *ServerConfig
```

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

### Compare two models

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Compares two language models by running a specified number of turn pairs, with a starter prompt, and optionally showing token usage.

```bash
toro pingpong \
  --models "gpt-4o,claude-3-opus" \
  --turn-pairs 5 \
  --starter "Explain machine learning" \
  --show-tokens words
```

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

### torod serve Command

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

Command to run the TokenRouter server.

```bash
torod serve [flags]
```

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

### Wrap command basic usage

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/cli-reference.md

A generic wrapper for executing any command with temporary TokenRouter credentials.

```bash
toro wrap [wrapper_flags] -- <command> [args...]
```

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

### Embeddings Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON response for the Embeddings endpoint.

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1, 0.2, 0.3, ...],
      "index": 0
    }
  ],
  "model": "provider/model-id",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}
```

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

### DefaultServerConfigPath

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Returns default configuration file path.

```go
func DefaultServerConfigPath() string
```

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

### AddIncomingToken

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/config-store.md

Adds a new API token.

```go
func (s *ServerConfigStore) AddIncomingToken(t IncomingAPIToken) error
```

```go
token := config.IncomingAPIToken{
	ID:       "token-123",
	Name:     "API Key",
	Role:     "inferrer",
	Key:      "sk-...",
	ExpiresAt: "2025-12-31T23:59:59Z",
}
if err := store.AddIncomingToken(token); err != nil {
	log.Fatalf("Failed to add token: %v", err)
}
```

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

### Model Resolution Error Handling

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/api-reference/provider-resolver.md

Example of handling model resolution errors.

```Go
provider, model, err := resolver.ResolveModel("unknown-provider/model")
if err != nil {
	// Handle: provider not found, model not found, discovery failed
}
```

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

### Admin Logout Response

Source: https://github.com/lkarlslund/tokenrouter/blob/master/_autodocs/endpoints.md

Example JSON response for admin logout.

```json
{
  "authenticated": false
}
```