Pi Web Model Management API Endpoints: Complete REST Reference

Pi Web exposes REST endpoints under /api/models and /api/models-config for retrieving available models, persisting provider configurations, discovering upstream offerings, and testing connectivity.

The agegr/pi-web repository implements a comprehensive model management layer through Next.js API routes, enabling dynamic configuration of AI providers without restarts. These endpoints read from and write to ~/.pi/agent/settings.json and models.json, interfacing with the Pi SDK's AuthStorage and ModelRegistry to maintain state between sessions.

Core Model Listing Endpoint

GET /api/models

The primary retrieval endpoint lives in app/api/models/route.ts. This route aggregates three distinct data sources into a single response:

• The complete list of available models from the internal provider registry
• The full model list from configured upstream providers
• The user's default model selection (read from ~/.pi/agent/settings.json)

When a client sends a GET request to /api/models, the handler queries the ModelRegistry for registered providers, merges this with persisted user preferences, and returns a unified JSON payload suitable for populating model selection dropdowns in the UI.

Configuration Management Endpoints

The /api/models-config namespace handles CRUD operations for provider-specific settings, including API keys, model selections, and default routing.

Retrieving and Updating Configuration

GET /api/models-config : Returns the contents of models.json containing provider-specific model selections, API key bindings, and user preferences. Implemented in app/api/models-config/route.ts.

PUT /api/models-config : Validates and writes a new JSON configuration structure to persist user changes. The request body must contain the complete configuration object, which the route validates against the expected schema before writing to disk. Also located in app/api/models-config/route.ts.

Dynamic Model Discovery

POST /api/models-config/discover : Located in app/api/models-config/discover/route.ts, this endpoint accepts a provider name (e.g., anthropic, openai) in the request body. It then contacts the provider's upstream API to fetch the current list of available models, returning the discovered list for display in configuration interfaces without requiring manual model ID entry.

Connectivity Testing

POST /api/models-config/test : Implemented in app/api/models-config/test/route.ts, this endpoint performs a lightweight validation request (typically a single-token completion) to verify that a specific model configuration is reachable and properly authenticated. It accepts provider and model identifiers, returns success/failure details, and helps prevent saving invalid configurations.

Curated Model Catalog

GET /api/models-config/catalog : Serves a static, curated catalog of pricing-preset models (such as the "models.dev" preset) from app/api/models-config/catalog/route.ts. This endpoint provides quick-selection options for common model tiers without requiring users to know specific model IDs.

Source Code Architecture

Pi Web uses the Next.js App Router convention where filesystem paths automatically map to HTTP endpoints. The model management layer spans five primary implementation files:

• app/api/models/route.ts – Aggregates model listing and default selection logic
• app/api/models-config/route.ts – Handles configuration persistence via GET/PUT
• app/api/models-config/catalog/route.ts – Serves static pricing presets
• app/api/models-config/discover/route.ts – Proxies provider discovery requests
• app/api/models-config/test/route.ts – Executes connectivity validation

Each route imports from the Pi SDK to interact with AuthStorage for encrypted credential handling and ModelRegistry for provider metadata resolution.

Client Integration Examples

The following JavaScript snippets demonstrate the HTTP contract for interacting with these endpoints directly:

Retrieve the current model list and default selection:

const response = await fetch('/api/models');
const { models, defaultModel } = await response.json();
console.log('Available:', models, 'Default:', defaultModel);

Fetch the persisted configuration:

const config = await fetch('/api/models-config').then(r => r.json());
console.log('Current providers:', config.providers);

Update provider settings with validation:

const newConfig = {
  providers: {
    openai: { apiKey: 'sk-...', modelId: 'gpt-4o' },
    anthropic: { apiKey: '...', modelId: 'claude-3-sonnet-20240229' }
  },
  defaultModel: 'openai:gpt-4o'
};

const result = await fetch('/api/models-config', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(newConfig)
});

Discover models from a specific provider:

const discovered = await fetch('/api/models-config/discover', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ provider: 'openai' })
}).then(r => r.json());

Test connectivity before saving:

const testResult = await fetch('/api/models-config/test', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    provider: 'anthropic', 
    modelId: 'claude-3-sonnet-20240229' 
  })
}).then(r => r.json());

Summary

• Endpoint Overview: Pi Web provides six distinct endpoints across /api/models and /api/models-config namespaces for complete model lifecycle management.
• File Locations: Implementation resides in app/api/models/route.ts and four files under app/api/models-config/ (route.ts, catalog, discover, and test subroutes).
• Core Capabilities: Read available models, persist configuration to models.json, discover upstream offerings dynamically, and validate connectivity before committing changes.
• SDK Integration: All routes leverage the Pi SDK's AuthStorage and ModelRegistry for secure credential handling and provider metadata management.

Frequently Asked Questions

What is the difference between /api/models and /api/models-config?

The /api/models endpoint returns aggregated runtime data including available models and the current default selection, while /api/models-config handles the persistence layer for user-specific settings like API keys and preferred model IDs stored in models.json.

How does Pi Web discover new models from providers?

The POST /api/models-config/discover endpoint in app/api/models-config/discover/route.ts proxies requests to provider APIs (such as OpenAI or Anthropic), fetching current model listings and returning them to the UI for selection without requiring manual ID entry.

Where is the model configuration stored persistently?

Configuration is stored in models.json within the user's home directory under ~/.pi/agent/, with the /api/models-config endpoints providing the read and write interface to this file according to the logic in app/api/models-config/route.ts.

How can I verify a model configuration is working before saving it?

Send a POST request to /api/models-config/test with the provider and model ID; the endpoint implemented in app/api/models-config/test/route.ts executes a lightweight completion request to verify connectivity and authentication before you commit the configuration via the PUT endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}