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

# aiGateways

> OpenAI-compatible model routing with provider-neutral models, tenant budgets, retries, redacted audit events, and unified usage.

OpenAI-compatible model routing with provider-neutral models, tenant budgets, retries, redacted audit events, and unified usage.

## aiGateways.list

List AI gateways in one project environment.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/ai-gateways
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways?environment=example" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                   |
| ------ | --------------------------------------------- |
| `200`  | AI gateways with batched current-month usage. |

### Response body (200)

An array of objects with these fields:

| Field                | Type      | Description          |
| -------------------- | --------- | -------------------- |
| `id`                 | string    | —                    |
| `name`               | string    | —                    |
| `environment`        | string    | —                    |
| `allowedModels`      | string\[] | —                    |
| `monthlyBudgetUsd`   | number    | —                    |
| `timeoutMs`          | integer   | —                    |
| `maxRetries`         | integer   | —                    |
| `redactPrompts`      | boolean   | —                    |
| `createdAt`          | string    | Format: `date-time`. |
| `updatedAt`          | string    | Format: `date-time`. |
| `usage`              | object    | —                    |
| `usage.month`        | string    | Format: `date-time`. |
| `usage.requests`     | integer   | —                    |
| `usage.inputTokens`  | integer   | —                    |
| `usage.outputTokens` | integer   | —                    |
| `usage.spentUsd`     | number    | —                    |
| `usage.budgetUsd`    | number    | —                    |
| `usage.remainingUsd` | number    | —                    |

## aiGateways.create

Create a budgeted AI gateway in one project environment.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/ai-gateways
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Request body

| Field              | Type      | Required | Description                        |
| ------------------ | --------- | -------- | ---------------------------------- |
| `name`             | string    | Yes      | Pattern: `^[a-z][a-z0-9-]{1,61}$`. |
| `allowedModels`    | string\[] | Yes      | —                                  |
| `monthlyBudgetUsd` | number    | Yes      | —                                  |
| `timeoutMs`        | integer   | No       | —                                  |
| `maxRetries`       | integer   | No       | —                                  |
| `redactPrompts`    | boolean   | No       | —                                  |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "allowedModels": [
    "korve/fast"
  ],
  "monthlyBudgetUsd": 1
}'
```

### Responses

| Status | Description                      |
| ------ | -------------------------------- |
| `201`  | AI gateway created.              |
| `409`  | The gateway name already exists. |
| `422`  | Invalid gateway configuration.   |

### Response body (201)

| Field              | Type      | Description          |
| ------------------ | --------- | -------------------- |
| `id`               | string    | —                    |
| `name`             | string    | —                    |
| `environment`      | string    | —                    |
| `allowedModels`    | string\[] | —                    |
| `monthlyBudgetUsd` | number    | —                    |
| `timeoutMs`        | integer   | —                    |
| `maxRetries`       | integer   | —                    |
| `redactPrompts`    | boolean   | —                    |
| `createdAt`        | string    | Format: `date-time`. |
| `updatedAt`        | string    | Format: `date-time`. |

## aiGateways.get

Get AI gateway configuration.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description      |
| ------ | ---------------- |
| `200`  | AI gateway.      |
| `404`  | No such gateway. |

### Response body (200)

| Field              | Type      | Description          |
| ------------------ | --------- | -------------------- |
| `id`               | string    | —                    |
| `name`             | string    | —                    |
| `environment`      | string    | —                    |
| `allowedModels`    | string\[] | —                    |
| `monthlyBudgetUsd` | number    | —                    |
| `timeoutMs`        | integer   | —                    |
| `maxRetries`       | integer   | —                    |
| `redactPrompts`    | boolean   | —                    |
| `createdAt`        | string    | Format: `date-time`. |
| `updatedAt`        | string    | Format: `date-time`. |

## aiGateways.update

Update model allowlists, budget, timeout, retry, and prompt-retention policy.

```text theme={null}
PATCH /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Request body

| Field              | Type      | Required | Description                        |
| ------------------ | --------- | -------- | ---------------------------------- |
| `name`             | string    | No       | Pattern: `^[a-z][a-z0-9-]{1,61}$`. |
| `allowedModels`    | string\[] | No       | —                                  |
| `monthlyBudgetUsd` | number    | No       | —                                  |
| `timeoutMs`        | integer   | No       | —                                  |
| `maxRetries`       | integer   | No       | —                                  |
| `redactPrompts`    | boolean   | No       | —                                  |

### Example

```bash theme={null}
curl -X PATCH "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example"
}'
```

### Responses

| Status | Description                    |
| ------ | ------------------------------ |
| `200`  | Updated AI gateway.            |
| `404`  | No such gateway.               |
| `422`  | Invalid gateway configuration. |

### Response body (200)

| Field              | Type      | Description          |
| ------------------ | --------- | -------------------- |
| `id`               | string    | —                    |
| `name`             | string    | —                    |
| `environment`      | string    | —                    |
| `allowedModels`    | string\[] | —                    |
| `monthlyBudgetUsd` | number    | —                    |
| `timeoutMs`        | integer   | —                    |
| `maxRetries`       | integer   | —                    |
| `redactPrompts`    | boolean   | —                    |
| `createdAt`        | string    | Format: `date-time`. |
| `updatedAt`        | string    | Format: `date-time`. |

## aiGateways.delete

Permanently delete an AI gateway and revoke every gateway key.

```text theme={null}
DELETE /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `owner`
* **Risk:** `destructive` · sensitive (elevated blast radius)

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description         |
| ------ | ------------------- |
| `200`  | AI gateway deleted. |
| `404`  | No such gateway.    |

### Response body (200)

| Field | Type    | Description     |
| ----- | ------- | --------------- |
| `ok`  | boolean | One of: `true`. |

## aiGateways.models

List provider-neutral models available through this gateway.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}/models
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID/models" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description       |
| ------ | ----------------- |
| `200`  | Available models. |

### Response body (200)

One of: `korve/fast`, `korve/balanced`, `korve/reasoning`.

## aiGateways.listKeys

List gateway key metadata. Secret values are never returned.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}/keys
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Risk:** `read` · sensitive (elevated blast radius)

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID/keys" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description   |
| ------ | ------------- |
| `200`  | Gateway keys. |

### Response body (200)

An array of objects with these fields:

| Field        | Type           | Description          |
| ------------ | -------------- | -------------------- |
| `id`         | string         | Format: `uuid`.      |
| `name`       | string         | —                    |
| `keyPrefix`  | string         | —                    |
| `lastUsedAt` | string or null | Format: `date-time`. |
| `revokedAt`  | string or null | Format: `date-time`. |
| `createdAt`  | string         | Format: `date-time`. |

## aiGateways.createKey

Create a least-privilege gateway key. The secret is returned exactly once.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}/keys
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write` · sensitive (elevated blast radius)

### Request body

| Field  | Type   | Required | Description |
| ------ | ------ | -------- | ----------- |
| `name` | string | Yes      | —           |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID/keys" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront"
}'
```

### Responses

| Status | Description                       |
| ------ | --------------------------------- |
| `201`  | Key metadata and one-time secret. |
| `404`  | No such gateway.                  |

### Response body (201)

| Field       | Type   | Description                     |
| ----------- | ------ | ------------------------------- |
| `id`        | string | Format: `uuid`.                 |
| `name`      | string | —                               |
| `keyPrefix` | string | —                               |
| `secret`    | string | Pattern: `^kvgw_[A-Za-z0-9]+$`. |

## aiGateways.revokeKey

Permanently revoke a gateway key.

```text theme={null}
DELETE /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}/keys/{keyId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Risk:** `destructive` · sensitive (elevated blast radius)

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID/keys/$KEY_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description  |
| ------ | ------------ |
| `200`  | Key revoked. |
| `404`  | No such key. |

### Response body (200)

| Field | Type    | Description     |
| ----- | ------- | --------------- |
| `ok`  | boolean | One of: `true`. |

## aiGateways.usage

Get token and spend usage for the current billing month.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/ai-gateways/{gatewayId}/usage
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/ai-gateways/$GATEWAY_ID/usage" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                         |
| ------ | ----------------------------------- |
| `200`  | Gateway usage and remaining budget. |

### Response body (200)

| Field          | Type    | Description          |
| -------------- | ------- | -------------------- |
| `month`        | string  | Format: `date-time`. |
| `requests`     | integer | —                    |
| `inputTokens`  | integer | —                    |
| `outputTokens` | integer | —                    |
| `spentUsd`     | number  | —                    |
| `budgetUsd`    | number  | —                    |
| `remainingUsd` | number  | —                    |

## aiGateways.runtimeChatCompletions

Run an OpenAI-compatible chat completion using an injected runtime capability or a gateway-scoped key.

```text theme={null}
POST /v1/runtime/ai/{gatewayName}/chat/completions
```

* **Auth:** Project app-service token (`Authorization: Bearer $APP_SERVICE_TOKEN`).
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Request body

| Field                | Type      | Required | Description                                                |
| -------------------- | --------- | -------- | ---------------------------------------------------------- |
| `model`              | string    | Yes      | One of: `korve/fast`, `korve/balanced`, `korve/reasoning`. |
| `messages`           | object\[] | Yes      | —                                                          |
| `messages[].role`    | string    | Yes      | One of: `system`, `user`, `assistant`, `tool`.             |
| `messages[].content` | string    | Yes      | —                                                          |
| `stream`             | boolean   | No       | —                                                          |
| `max_tokens`         | integer   | No       | —                                                          |
| `temperature`        | number    | No       | —                                                          |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/runtime/ai/$GATEWAY_NAME/chat/completions" \
  -H "Authorization: Bearer $APP_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "korve/fast",
  "messages": [
    {
      "role": "system",
      "content": "example"
    }
  ]
}'
```

### Responses

| Status | Description                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | OpenAI-compatible JSON response when stream is false; text/event-stream chunks use the same opaque Korve completion id when stream is true. |
| `403`  | The requested model is not allowed.                                                                                                         |
| `404`  | No such gateway in the runtime environment.                                                                                                 |
| `429`  | The monthly gateway budget is exhausted.                                                                                                    |
| `503`  | Model inference is temporarily unavailable.                                                                                                 |

### Response body (200)

| Field                       | Type      | Description                                                |
| --------------------------- | --------- | ---------------------------------------------------------- |
| `id`                        | string    | Pattern: `^kvc_[a-f0-9]{32}$`.                             |
| `object`                    | string    | One of: `chat.completion`.                                 |
| `created`                   | integer   | —                                                          |
| `model`                     | string    | One of: `korve/fast`, `korve/balanced`, `korve/reasoning`. |
| `choices`                   | object\[] | —                                                          |
| `choices[].index`           | integer   | One of: `0`.                                               |
| `choices[].message`         | object    | —                                                          |
| `choices[].message.role`    | string    | One of: `assistant`.                                       |
| `choices[].message.content` | string    | —                                                          |
| `choices[].finish_reason`   | string    | One of: `stop`, `length`, `tool_calls`.                    |
| `usage`                     | object    | —                                                          |
| `usage.prompt_tokens`       | integer   | —                                                          |
| `usage.completion_tokens`   | integer   | —                                                          |
| `usage.total_tokens`        | integer   | —                                                          |