Proxy API - MeshAI Documentation

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.

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
  }'

{
  "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"
  }
}

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

List Proxy Keys

GET /proxy-keys

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}

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.

curl https://api.meshai.dev/api/v1/proxy/stats \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "total_requests_today": 1842,
    "total_tokens_today": 512340,
    "total_cost_today_usd": "12.4501",
    "active_proxy_keys": 6
  }
}

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.

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"
  }'

{
  "success": true,
  "data": {
    "id": "01HR33F9K7WZC2M8QXNVBT5R6D",
    "provider": "openai",
    "label": "org-openai-key",
    "created_at": "2026-03-17T10:00:00Z"
  }
}

List Managed Keys

GET /managed-keys

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}

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.

​Proxy Keys

​Create a Proxy Key

​List Proxy Keys

​Revoke a Proxy Key

​Proxy Stats

​Managed Provider Keys

​Create a Managed Key

​List Managed Keys

​Delete a Managed Key