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.
8 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| 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 | Set an app’s monthly AI budget, or null to use the one its manifest names (admins) |
| 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} | Rename a connection, change its models and prices, or replace its key (admins) |
| DELETE | /v1/workspaces/{ws}/ai/connections/{id} | Remove a connection and its sealed key (admins) |
| 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 | The model apps use when their manifest names none (admins) |
| 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_onlyfor 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.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).