<!-- source: https://modelux.ai/docs/api/overview -->

> Conventions for the Modelux proxy and management APIs.

# API overview

Modelux exposes two HTTP APIs:

- **Proxy API** at `https://api.modelux.ai/v1/*` — OpenAI-compatible surface for running inference. Authenticated with a project API key.
- **Management API** at `https://api.modelux.ai/manage/v1/*` — REST API for managing projects, routing configs, providers, budgets, analytics, etc. Authenticated with a management API key.

## Authentication

All API calls require a bearer token:

```
Authorization: Bearer mlx_sk_...        // proxy / project key
Authorization: Bearer mlx_mk_...        // management key
```

### API key prefixes

| Prefix | Use |
|---|---|
| `mlx_sk_` | Project API key — for the proxy API |
| `mlx_mk_` | Management API key — for the management API and MCP |

## Base URLs

| Environment | Base URL |
|---|---|
| Production | `https://api.modelux.ai` |
| Dev (self-hosted) | `http://localhost:8080` (proxy), `http://localhost:5100` (app) |

## Error format

Errors follow the OpenAI error shape for familiarity:

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: messages",
    "code": "missing_field"
  }
}
```

Management API errors use the same shape with additional fields where useful:

```json
{
  "error": {
    "type": "not_found",
    "message": "routing config @missing not found",
    "code": "routing_config_not_found",
    "resource": "routing_config",
    "id": "@missing"
  }
}
```

## Status codes

| Code | Meaning |
|---|---|
| `200` | Success |
| `400` | Bad request — malformed input |
| `401` | Missing or invalid authentication |
| `402` | Payment required — budget exceeded |
| `403` | Forbidden — authenticated but lacks permission |
| `404` | Not found |
| `409` | Conflict — duplicate resource |
| `422` | Unprocessable entity — validation failed |
| `429` | Rate limited |
| `500` | Server error — check status page |
| `502`/`504` | Upstream provider error or timeout |

## Rate limits

Proxy API limits are per-API-key. Default: 600 requests/minute. Upgrade tiers
increase this. Custom limits can be set per key.

Management API: 60 req/min per management key.

## Idempotency

Mutating management API endpoints accept an `Idempotency-Key` header. Same
key + same body returns the original response within 24 hours.

## Pagination

Management API list endpoints return:

```json
{
  "data": [...],
  "next_cursor": "opaque_cursor_or_null",
  "has_more": true
}
```

Pass `?cursor=...` to fetch the next page.