# Pi Web Model Management API Endpoints: Complete REST Reference

> Explore the Pi Web Model Management API endpoints for complete REST reference. Discover how to manage models, configurations, and connectivity via the /api/models and /api/models-config routes.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: api-reference
- Published: 2026-07-30

---

**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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/models.json) containing provider-specific model selections, API key bindings, and user preferences. Implemented in [`app/api/models-config/route.ts`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/route.ts).

### Dynamic Model Discovery

**POST /api/models-config/discover**
: Located in [`app/api/models-config/discover/route.ts`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/app/api/models/route.ts) – Aggregates model listing and default selection logic
- [`app/api/models-config/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/route.ts) – Handles configuration persistence via GET/PUT
- [`app/api/models-config/catalog/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/catalog/route.ts) – Serves static pricing presets
- [`app/api/models-config/discover/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/discover/route.ts) – Proxies provider discovery requests
- [`app/api/models-config/test/route.ts`](https://github.com/agegr/pi-web/blob/main/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:

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

```

Fetch the persisted configuration:

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

```

Update provider settings with validation:

```javascript
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:

```javascript
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:

```javascript
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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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.