# capguard

 3 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/capguard/

3 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/​apps/​{id}/​shield`](#get-v1-apps-id-shield) | An app's limits against floods and its traffic over the last week |
| [[PUT]] | [`/​v1/​apps/​{id}/​shield`](#put-v1-apps-id-shield) | Change an app's limits, or wake it after a flood (workspace admins) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​capguard`](#get-v1-workspaces-ws-capguard) | What the spending cap holds right now, what waits, and what is asleep |

## Reference

### [[GET]] `/v1/apps/{id}/shield`

An app's limits against floods and its traffic over the last week.

- **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:** `can_edit` on the app

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `settings` | object | yes |  |
| `settings.dailyCap` | integer or null | yes | 100 to 1000000000 |
| `settings.perVisitorPerMin` | integer | yes | 10 to 6000 |
| `settings.perAppPerMin` | integer | yes | 60 to 120000 |
| `settings.blockCrawlers` | boolean | yes |  |
| `settings.sleepUnderAttack` | boolean | yes |  |
| `isDefault` | boolean | yes |  |
| `suggestedDailyCap` | integer | yes | at least 100 |
| `asleep` | object or null | yes |  |
| `asleep.reason` | "cap" · "daily_cap" · "attack" | yes |  |
| `asleep.until` | string (date-time) or null | yes |  |
| `today` | object | yes |  |
| `today.day` | string (date) | yes |  |
| `today.forwarded` | integer | yes | at least 0 |
| `today.throttled` | integer | yes | at least 0 |
| `today.blocked` | integer | yes | at least 0 |
| `today.asleep` | integer | yes | at least 0 |
| `today.dailyCapped` | integer | yes | at least 0 |
| `last7` | object[] | yes | up to 14 items |
| `last7[].day` | string (date) | yes |  |
| `last7[].forwarded` | integer | yes | at least 0 |
| `last7[].throttled` | integer | yes | at least 0 |
| `last7[].blocked` | integer | yes | at least 0 |
| `last7[].asleep` | integer | yes | at least 0 |
| `last7[].dailyCapped` | integer | yes | at least 0 |
| `canChange` | boolean | yes |  |
| `notes` | string[] | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PUT]] `/v1/apps/{id}/shield`

Change an app's limits, or wake it after a flood (workspace 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:** workspace admin (and `can_edit`)

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `settings` | object |  |  |
| `settings.dailyCap` | integer or null |  | 100 to 1000000000 |
| `settings.perVisitorPerMin` | integer |  | 10 to 6000 |
| `settings.perAppPerMin` | integer |  | 60 to 120000 |
| `settings.blockCrawlers` | boolean |  |  |
| `settings.sleepUnderAttack` | boolean |  |  |
| `wake` | boolean |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `settings` | object | yes |  |
| `settings.dailyCap` | integer or null | yes | 100 to 1000000000 |
| `settings.perVisitorPerMin` | integer | yes | 10 to 6000 |
| `settings.perAppPerMin` | integer | yes | 60 to 120000 |
| `settings.blockCrawlers` | boolean | yes |  |
| `settings.sleepUnderAttack` | boolean | yes |  |
| `isDefault` | boolean | yes |  |
| `suggestedDailyCap` | integer | yes | at least 100 |
| `asleep` | object or null | yes |  |
| `asleep.reason` | "cap" · "daily_cap" · "attack" | yes |  |
| `asleep.until` | string (date-time) or null | yes |  |
| `today` | object | yes |  |
| `today.day` | string (date) | yes |  |
| `today.forwarded` | integer | yes | at least 0 |
| `today.throttled` | integer | yes | at least 0 |
| `today.blocked` | integer | yes | at least 0 |
| `today.asleep` | integer | yes | at least 0 |
| `today.dailyCapped` | integer | yes | at least 0 |
| `last7` | object[] | yes | up to 14 items |
| `last7[].day` | string (date) | yes |  |
| `last7[].forwarded` | integer | yes | at least 0 |
| `last7[].throttled` | integer | yes | at least 0 |
| `last7[].blocked` | integer | yes | at least 0 |
| `last7[].asleep` | integer | yes | at least 0 |
| `last7[].dailyCapped` | integer | yes | at least 0 |
| `canChange` | boolean | yes |  |
| `notes` | string[] | yes |  |

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}/capguard`

What the spending cap holds right now, what waits, and what is asleep.

- **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

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `asOf` | string (date-time) | yes |  |
| `hardCap` | boolean | yes |  |
| `units` | object[] | yes |  |
| `units[].kind` | "requests" · "runs" · "ai_credits" | yes |  |
| `units[].stops` | "apps" · "runs" · "builds" | yes |  |
| `units[].used` | number | yes | at least 0 |
| `units[].limit` | number | yes | at least 0 |
| `units[].graceLimit` | number | yes | at least 0 |
| `units[].remaining` | number | yes | at least 0 |
| `units[].pct` | number | yes | 0 to 1000 |
| `units[].level` | "ok" · "warn" · "held" · "off" | yes |  |
| `holds` | object | yes |  |
| `holds.apps` | object or null | yes |  |
| `holds.runs` | object or null | yes |  |
| `holds.builds` | object or null | yes |  |
| `runs` | object | yes |  |
| `runs.waiting` | integer | yes | at least 0 |
| `runs.oldestAt` | string (date-time) or null | yes |  |
| `runs.dropsAt` | string (date-time) or null | yes |  |
| `runs.droppedLastWeek` | integer | yes | at least 0 |
| `runs.folded` | integer | yes | at least 0 |
| `sleepingApps` | object[] | yes |  |
| `sleepingApps[].appId` | string | yes | at least 1 characters |
| `sleepingApps[].name` | string | yes | at least 1 characters |
| `sleepingApps[].reason` | "cap" · "daily_cap" · "attack" | yes |  |
| `sleepingApps[].until` | string (date-time) or null | yes |  |
| `enforcedWithinSeconds` | integer | yes | at least 1 |
| `notes` | string[] | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).