omni-providers

<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

## Overview

Manage provider connections, API keys, OAuth flows, and connection tests via the REST API. List, add, update, remove, and test AI provider integrations (OpenAI, Anthropic, Gemini, and 160+).

## Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via `POST /api/auth/login` or configure `REQUIRE_API_KEY=false` for local development.

## Endpoints

### GET /api/providers

List provider connections

```bash
curl https://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### POST /api/providers

Create provider connection

```bash
curl -X POST https://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### GET /api/providers/{id}

Get provider connection

```bash
curl https://localhost:20128/api/providers/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### PATCH /api/providers/{id}

Update provider connection

```bash
curl -X PATCH https://localhost:20128/api/providers/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### DELETE /api/providers/{id}

Delete provider connection

```bash
curl -X DELETE https://localhost:20128/api/providers/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### POST /api/providers/{id}/test

Test provider connection

```bash
curl -X POST https://localhost:20128/api/providers/{id}/test \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### GET /api/providers/{id}/models

List models for a provider

```bash
curl https://localhost:20128/api/providers/{id}/models \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### POST /api/providers/test-batch

Test multiple providers at once

```bash
curl -X POST https://localhost:20128/api/providers/test-batch \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### POST /api/providers/validate

Validate provider credentials

```bash
curl -X POST https://localhost:20128/api/providers/validate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### GET /api/providers/client

Get client-side provider info

```bash
curl https://localhost:20128/api/providers/client \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/provider-nodes

List provider nodes

```bash
curl https://localhost:20128/api/provider-nodes \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### POST /api/provider-nodes

Create provider node

```bash
curl -X POST https://localhost:20128/api/provider-nodes \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### PATCH /api/provider-nodes/{id}

Update provider node

```bash
curl -X PATCH https://localhost:20128/api/provider-nodes/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### DELETE /api/provider-nodes/{id}

Delete provider node

```bash
curl -X DELETE https://localhost:20128/api/provider-nodes/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### POST /api/provider-nodes/validate

Validate a provider node

```bash
curl -X POST https://localhost:20128/api/provider-nodes/validate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'
```

### GET /api/provider-models

List provider models

```bash
curl https://localhost:20128/api/provider-models \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

## Payloads

See the full OpenAPI specification at `GET /api/openapi/spec` or `docs/reference/openapi.yaml` for detailed request/response schemas.

<!-- skill:custom-start -->
## Additional endpoints

### POST /api/providers/{id}/refresh

Rotate / refresh OAuth tokens or re-validate credentials for a provider connection. Useful after token expiration or when credentials need to be renewed without deleting the connection.

```bash
curl -X POST https://localhost:20128/api/providers/{id}/refresh \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### GET /api/provider-metrics

Retrieve aggregated usage and performance metrics for all provider connections (request counts, error rates, latency percentiles, token usage). Used by dashboards and Auto-Combo scoring.

```bash
curl https://localhost:20128/api/provider-metrics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

**Response example:**
```json
{
  "providers": [
    {
      "id": "my-openai",
      "requestCount": 1240,
      "errorRate": 0.02,
      "p50LatencyMs": 340,
      "p99LatencyMs": 1200,
      "tokensIn": 500000,
      "tokensOut": 250000
    }
  ]
}
```

### GET /api/providers/health-matrix

Returns a health-matrix view of all providers with per-connection status, circuit-breaker state, and cooldown expiry. Useful for debugging routing decisions.

```bash
curl https://localhost:20128/api/providers/health-matrix \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```
<!-- skill:custom-end -->