# AI models The workspace’s own model provider keys, the default model, each app’s monthly budget and the usage report. 8 routes, from the API’s own OpenAPI document. URL: https://docs.qaldy.com/reference/api/models/ 8 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/). ## Routes | Method | Path | What it does | |---|---|---| | [[GET]] | [`/​v1/​workspaces/​{ws}/​ai`](#get-v1-workspaces-ws-ai) | Model connections, the default model and, for admins, each app’s AI budget | | [[PUT]] | [`/​v1/​workspaces/​{ws}/​ai/​apps/​{appId}/​budget`](#put-v1-workspaces-ws-ai-apps-appid-budget) | Set an app’s monthly AI budget, or null to use the one its manifest names (admins) | | [[POST]] | [`/​v1/​workspaces/​{ws}/​ai/​connections`](#post-v1-workspaces-ws-ai-connections) | Add a model provider: the key is sealed to the gate and never returned (admins) | | [[PUT]] | [`/​v1/​workspaces/​{ws}/​ai/​connections/​{id}`](#put-v1-workspaces-ws-ai-connections-id) | Rename a connection, change its models and prices, or replace its key (admins) | | [[DELETE]] | [`/​v1/​workspaces/​{ws}/​ai/​connections/​{id}`](#delete-v1-workspaces-ws-ai-connections-id) | Remove a connection and its sealed key (admins) | | [[POST]] | [`/​v1/​workspaces/​{ws}/​ai/​connections/​{id}/​test`](#post-v1-workspaces-ws-ai-connections-id-test) | Test the key: the gate asks the provider for its model list, no tokens (admins) | | [[PUT]] | [`/​v1/​workspaces/​{ws}/​ai/​default-model`](#put-v1-workspaces-ws-ai-default-model) | The model apps use when their manifest names none (admins) | | [[GET]] | [`/​v1/​workspaces/​{ws}/​ai/​usage`](#get-v1-workspaces-ws-ai-usage) | Model use by day, app and model: tokens and cost at your prices (apps you can view) | ## Reference ### [[GET]] `/v1/workspaces/{ws}/ai` Model connections, the default model and, for admins, each app’s AI budget. - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** member (money and apps: admin) | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `available` | boolean | yes | | | `unavailable` | object or null | yes | | | `unavailable.reason` | "no_connection" · "profile" | yes | | | `unavailable.message` | string | yes | | | `unavailable.hint` | string | yes | | | `canManage` | boolean | yes | | | `connections` | object[] | yes | | | `connections[].id` | string | yes | | | `connections[].provider` | "anthropic" · "openai" · "openai-compatible" | yes | | | `connections[].label` | string | yes | | | `connections[].baseUrl` | string | yes | | | `connections[].host` | string | yes | | | `connections[].models` | object[] | yes | | | `connections[].keyState` | "write-only" | yes | | | `connections[].keyId` | string | yes | | | `connections[].status` | "connected" · "error" | yes | | | `connections[].createdAt` | string (date-time) | yes | | | `connections[].updatedAt` | string (date-time) | yes | | | `defaultModel` | string or null | yes | 1 to 80 characters | | `month` | object | yes | | | `month.start` | string (date) | yes | | | `month.end` | string (date) | yes | | | `apps` | object[] | yes | | | `apps[].appId` | string | yes | | | `apps[].name` | string | yes | | | `apps[].declared` | object | yes | | | `apps[].budgetUsd` | number | yes | at least 0 | | `apps[].budgetSource` | "manifest" · "override" | yes | | | `apps[].manifestBudgetUsd` | number | yes | at least 0 | | `apps[].spentUsd` | number | yes | at least 0 | …and 3 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json). Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[PUT]] `/v1/workspaces/{ws}/ai/apps/{appId}/budget` Set an app’s monthly AI budget, or null to use the one its manifest names (admins). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin, not a token | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `appId` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `monthlyBudgetUsd` | number or null | yes | 0 to 10000 | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `appId` | string | yes | | | `name` | string | yes | | | `declared` | object | yes | | | `declared.profile` | "standard" · "private" | yes | | | `declared.monthlyBudgetUsd` | number | yes | at least 0 | | `declared.models` | string[] | yes | | | `budgetUsd` | number | yes | at least 0 | | `budgetSource` | "manifest" · "override" | yes | | | `manifestBudgetUsd` | number | yes | at least 0 | | `spentUsd` | number | yes | at least 0 | | `calls` | integer | yes | at least 0 | | `missingModels` | string[] | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/workspaces/{ws}/ai/connections` Add a model provider: the key is sealed to the gate and never returned (admins). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin, not a token | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `provider` | "anthropic" · "openai" · "openai-compatible" | yes | | | `label` | string | yes | 2 to 60 characters | | `baseUrl` | string | | up to 300 characters | | `apiKey` | string | yes | up to 576 characters | | `models` | object[] | yes | up to 16 items | | `models[].id` | string | yes | 1 to 80 characters | | `models[].inputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].outputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].maxOutputTokens` | integer | | 1 to 200000 | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `id` | string | yes | | | `provider` | "anthropic" · "openai" · "openai-compatible" | yes | | | `label` | string | yes | | | `baseUrl` | string | yes | | | `host` | string | yes | | | `models` | object[] | yes | | | `models[].id` | string | yes | 1 to 80 characters | | `models[].inputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].outputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].maxOutputTokens` | integer | | 1 to 200000 | | `keyState` | "write-only" | yes | | | `keyId` | string | yes | | | `status` | "connected" · "error" | yes | | | `createdAt` | string (date-time) | yes | | | `updatedAt` | string (date-time) | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[PUT]] `/v1/workspaces/{ws}/ai/connections/{id}` Rename a connection, change its models and prices, or replace its key (admins). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin, not a token | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `id` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `label` | string | yes | 2 to 60 characters | | `models` | object[] | yes | up to 16 items | | `models[].id` | string | yes | 1 to 80 characters | | `models[].inputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].outputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].maxOutputTokens` | integer | | 1 to 200000 | | `apiKey` | string | | up to 576 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `id` | string | yes | | | `provider` | "anthropic" · "openai" · "openai-compatible" | yes | | | `label` | string | yes | | | `baseUrl` | string | yes | | | `host` | string | yes | | | `models` | object[] | yes | | | `models[].id` | string | yes | 1 to 80 characters | | `models[].inputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].outputUsdPerMTok` | number | yes | 0 to 1000 | | `models[].maxOutputTokens` | integer | | 1 to 200000 | | `keyState` | "write-only" | yes | | | `keyId` | string | yes | | | `status` | "connected" · "error" | yes | | | `createdAt` | string (date-time) | yes | | | `updatedAt` | string (date-time) | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[DELETE]] `/v1/workspaces/{ws}/ai/connections/{id}` Remove a connection and its sealed key (admins). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin, not a token | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `id` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `ok` | true | yes | | | `affectedApps` | string[] | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/workspaces/{ws}/ai/connections/{id}/test` Test the key: the gate asks the provider for its model list, no tokens (admins). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `id` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `checked` | "gate" · "unreachable" · "mock" | yes | | | `ok` | boolean or null | yes | | | `status` | integer or null | yes | 0 to 999 | | `latencyMs` | integer or null | yes | at least 0 | | `reason` | "auth_rejected" · "upstream_error" · "upstream_failed" · "dns_failed" · "private_address" · "secret_unavailable" · "invalid_config" · null or null | yes | | | `connection` | object | yes | | | `connection.id` | string | yes | | | `connection.provider` | "anthropic" · "openai" · "openai-compatible" | yes | | | `connection.label` | string | yes | | | `connection.baseUrl` | string | yes | | | `connection.host` | string | yes | | | `connection.models` | object[] | yes | | | `connection.keyState` | "write-only" | yes | | | `connection.keyId` | string | yes | | | `connection.status` | "connected" · "error" | yes | | | `connection.createdAt` | string (date-time) | yes | | | `connection.updatedAt` | string (date-time) | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[PUT]] `/v1/workspaces/{ws}/ai/default-model` The model apps use when their manifest names none (admins). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin, not a token | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `model` | string | yes | 1 to 80 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `defaultModel` | string | yes | 1 to 80 characters | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[GET]] `/v1/workspaces/{ws}/ai/usage` Model use by day, app and model: tokens and cost at your prices (apps you can view). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** admin; one `appId`: anyone who can open the app | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `range` | query | "7d" · "30d" · "90d" | | default "30d" | | `appId` | query | string | | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `range` | "7d" · "30d" · "90d" | yes | | | `appId` | string or null | yes | | | `timezone` | string | yes | | | `generatedAt` | string (date-time) | yes | | | `from` | string (date) | yes | | | `to` | string (date) | yes | | | `monthStart` | string (date) | yes | | | `totals` | object | yes | | | `totals.calls` | integer | yes | at least 0 | | `totals.refused` | integer | yes | at least 0 | | `totals.inputTokens` | number | yes | at least 0 | | `totals.outputTokens` | number | yes | at least 0 | | `totals.costUsd` | number | yes | at least 0 | | `daily` | object[] | yes | | | `daily[].day` | string (date) | yes | | | `daily[].calls` | integer | yes | at least 0 | | `daily[].refused` | integer | yes | at least 0 | | `daily[].inputTokens` | number | yes | at least 0 | | `daily[].outputTokens` | number | yes | at least 0 | | `daily[].costUsd` | number | yes | at least 0 | | `byApp` | object[] | yes | | | `byApp[].appId` | string | yes | | | `byApp[].name` | string or null | yes | | | `byApp[].calls` | integer | yes | at least 0 | | `byApp[].refused` | integer | yes | at least 0 | | `byApp[].inputTokens` | number | yes | at least 0 | | `byApp[].outputTokens` | number | yes | at least 0 | | `byApp[].costUsd` | number | yes | at least 0 | | `byApp[].budgetUsd` | number or null | yes | at least 0 | | `byApp[].budgetSource` | "manifest" · "override" · null or null | yes | | …and 2 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json). Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).