> ## 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.

# Budgets

> Monthly spend caps per project. Budgets watch month-to-date usage at rate-card prices and flag (or, with hard stop, will suspend) overruns.

Monthly spend caps per project. Budgets watch month-to-date usage at rate-card prices and flag (or, with hard stop, will suspend) overruns.

## budgets.get

Get the project's budget and month-to-date spend.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/budget
```

* **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/budget" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                            |
| ------ | -------------------------------------- |
| `200`  | The budget.                            |
| `404`  | No budget configured for this project. |

### Response body (200)

| Field             | Type    | Description                                                      |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `monthlyCapUsd`   | number  | —                                                                |
| `hardStop`        | boolean | Whether spend past the cap suspends the project's paid activity. |
| `alertAtPercent`  | integer | Alert threshold as a percent of the cap.                         |
| `currentSpendUsd` | number  | Month-to-date spend at rate-card prices.                         |

## budgets.set

Create or replace the project's budget. Omitted optional fields reset to defaults.

```text theme={null}
PUT /v1/orgs/{orgId}/projects/{projectId}/budget
```

* **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                      |
| ---------------- | ------- | -------- | -------------------------------- |
| `monthlyCapUsd`  | number  | Yes      | Monthly cap in USD. Must be > 0. |
| `hardStop`       | boolean | No       | Defaults to false.               |
| `alertAtPercent` | integer | No       | 1-100. Defaults to 80.           |

### Example

```bash theme={null}
curl -X PUT "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/budget" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "monthlyCapUsd": 50,
  "hardStop": false,
  "alertAtPercent": 80
}'
```

### Responses

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| `200`  | Budget stored.                                   |
| `402`  | Organization billing is not active.              |
| `404`  | No such project in this organization.            |
| `422`  | Invalid cap, hard stop flag, or alert threshold. |

### Response body (200)

| Field             | Type    | Description                                                      |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `monthlyCapUsd`   | number  | —                                                                |
| `hardStop`        | boolean | Whether spend past the cap suspends the project's paid activity. |
| `alertAtPercent`  | integer | Alert threshold as a percent of the cap.                         |
| `currentSpendUsd` | number  | Month-to-date spend at rate-card prices.                         |

## budgets.delete

Remove the project's budget. Usage keeps accruing, uncapped.

```text theme={null}
DELETE /v1/orgs/{orgId}/projects/{projectId}/budget
```

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

### Example

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

### Responses

| Status | Description                            |
| ------ | -------------------------------------- |
| `200`  | Budget removed.                        |
| `404`  | No budget configured for this project. |