> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy API

> Proxy keys, managed provider keys, and proxy usage stats

Creating a proxy key or managed key puts MeshAI's proxy in front of an agent, which enables enforcement (budget blocking, policy enforcement). Both require Starter plan or above; free tenants get a `402` upgrade-required response.

## Proxy Keys

### Create a Proxy Key

```
POST /proxy-keys
```

Creates a proxy key for developer attribution. An agent is auto-created behind the key if one doesn't already exist.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/proxy-keys \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "developer_label": "jane-dev",
    "allowed_providers": ["openai", "anthropic"],
    "budget_limit_usd": 100.00,
    "expires_in_days": 90
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "api_key_id": "01HR2Y8QZKJ6XM4P9VNTWB3F7C",
      "key_prefix": "msh_a1b2",
      "developer_label": "jane-dev",
      "team_id": null,
      "agent_id": "01HQZXK3VJ3XZ9K8QYNPBC7G4T",
      "allowed_providers": ["openai", "anthropic"],
      "budget_limit_usd": 100.00,
      "allowed_models": null,
      "model_overrides": null,
      "rate_limit_override": null,
      "use_managed_key": false,
      "created_at": "2026-03-17T10:00:00Z",
      "raw_key": "msh_a1b2c3d4e5f6g7h8i9j0"
    }
  }
  ```
</ResponseExample>

The `raw_key` is shown once, at creation time. Store it securely; it cannot be retrieved again.

### List Proxy Keys

```
GET /proxy-keys
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/proxy-keys \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Revoke a Proxy Key

```
DELETE /proxy-keys/{api_key_id}
```

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/proxy-keys/01HR2Y8QZKJ6XM4P9VNTWB3F7C \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns `204 No Content` on success.

## Proxy Stats

```
GET /proxy/stats
```

Today's proxy usage totals for the tenant.

```bash theme={null}
curl https://api.meshai.dev/api/v1/proxy/stats \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "total_requests_today": 1842,
      "total_tokens_today": 512340,
      "total_cost_today_usd": "12.4501",
      "active_proxy_keys": 6
    }
  }
  ```
</ResponseExample>

## Managed Provider Keys

Managed keys let MeshAI's proxy call a provider on the tenant's behalf using a key stored in AWS Secrets Manager. Only a secret reference is stored in MeshAI; the key value itself never passes through the API.

### Create a Managed Key

```
POST /managed-keys
```

`secret_ref` must be an AWS Secrets Manager name or ARN under the `meshai/managed/` prefix.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/managed-keys \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "label": "org-openai-key",
    "secret_ref": "meshai/managed/acme-corp/openai"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01HR33F9K7WZC2M8QXNVBT5R6D",
      "provider": "openai",
      "label": "org-openai-key",
      "created_at": "2026-03-17T10:00:00Z"
    }
  }
  ```
</ResponseExample>

### List Managed Keys

```
GET /managed-keys
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/managed-keys \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Delete a Managed Key

```
DELETE /managed-keys/{managed_key_id}
```

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/managed-keys/01HR33F9K7WZC2M8QXNVBT5R6D \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns `204 No Content` on success.