# ModelLens Public API

Agent-friendly REST API for discovering AI models across providers with filtering, pagination, and stable JSON responses.

- Version: v1
- Base URL: https://modellens.pages.dev/api/v1
- Discovery JSON: https://modellens.pages.dev/api/v1
- OpenAPI: https://modellens.pages.dev/api/v1/openapi.json
- Markdown: https://modellens.pages.dev/api/v1/README.md

## When to use this API

Use this public API for coding agents, scripts, SDK generation, and external integrations.
The website's internal endpoints are separate and are not the public contract.

## Recommended agent flow

1. Call `https://modellens.pages.dev/api/v1` to discover available endpoints and filter values.
2. Call `https://modellens.pages.dev/api/v1/models?provider=<provider>&limit=<n>` to list candidate models.
3. Read `https://modellens.pages.dev/api/v1/models/{provider}/{model_id}` for one exact model when needed.
4. Use `https://modellens.pages.dev/api/v1/openapi.json` if your tooling prefers OpenAPI.

## Supported filter values

- Providers: openai, anthropic, deepseek, google, mistral, groq, together
- Types: chat, embedding, image, audio, video
- Statuses: active, deprecated, unlisted
- Sort fields: updated, name, provider
- Sort orders: asc, desc

## markdown_docs

- Method: GET
- URL: https://modellens.pages.dev/api/v1/README.md
- Description: Raw Markdown documentation for agents and lightweight clients.

## list_models

- Method: GET
- URL: https://modellens.pages.dev/api/v1/models
- Description: List models with filtering, sorting, and pagination.

### Query parameters

- `page`: integer; default=1; min=1
- `limit`: integer; default=50; min=1; max=100
- `provider`: string; comma-separated; allowed=openai, anthropic, deepseek, google, mistral, groq, together
- `type`: string; comma-separated; allowed=chat, embedding, image, audio, video
- `status`: string; comma-separated; allowed=active, deprecated, unlisted
- `search`: string; Substring match against id, provider, name, and description.
- `sort`: string; default=updated; allowed=updated, name, provider
- `order`: string; default=desc; allowed=asc, desc

### Examples

- https://modellens.pages.dev/api/v1/models?provider=openai&limit=10
- https://modellens.pages.dev/api/v1/models?provider=anthropic,google&type=chat&status=active
- https://modellens.pages.dev/api/v1/models?search=vision&sort=name&order=asc&limit=25

## get_model

- Method: GET
- URL template: https://modellens.pages.dev/api/v1/models/{provider}/{model_id}
- Description: Fetch a single model by provider and model id returned by list_models.

### Path parameters

- `provider`: string; allowed=openai, anthropic, deepseek, google, mistral, groq, together
- `model_id`: string

### Example

- https://modellens.pages.dev/api/v1/models/{provider}/{model_id}

## list_providers

- Method: GET
- URL: https://modellens.pages.dev/api/v1/providers
- Description: List providers with model counts.

## get_stats

- Method: GET
- URL: https://modellens.pages.dev/api/v1/stats
- Description: Get aggregate model counts by provider, type, and status.

## Response conventions

- Collection endpoints return `data` and `meta`.
- Single-resource endpoints return `data`.
- Errors return `error.code` and `error.message`.

## Notes

- Prefer provider filters and small limits when an agent only needs a narrow set of models.
- Do not assume specific model ids remain current over time; discover them from `GET https://modellens.pages.dev/api/v1/models`.