# Budgets API

> Call the Budgets API: base URL, authentication, a first request, and every operation.

The Budgets API is a JSON API over HTTPS. Spending limits for projects, with alerts by email or webhook when spend or its forecast crosses a threshold.

## Base URL

```
https://budget.public.global.vexxhost.net
```

## Authentication

Send a token from [Identity](/identity/authentication) in the `X-Auth-Token` header with every request. See [Make API requests](/developer/api) for status codes and retries.

## Make your first request

List your project's budgets:

```sh
curl https://budget.public.global.vexxhost.net/v1/budgets \
  --header "X-Auth-Token: $TOKEN"
```

```json
{
  "budgets": [
    {
      "id": "c7e1a5b3-9d2f-4e8c-a6b4-1f3d5e7c9a2b",
      "name": "compute-monthly",
      "project_id": "a6f1c2d93b8e4f07b5d4e2c1a9f8e7d6",
      "enabled": true,
      "amount": "1000",
      "currency": "USD",
      "period": "monthly",
      "filter": {"services": ["compute"]},
      "thresholds": [
        {"name": "warn", "basis": "actual", "unit": "percentage", "value": "80",
         "comparison": "greater_than_or_equal", "enabled": true,
         "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]}
      ],
      "revision": 1,
      "created_by": "4c8e2f1a9b7d4e6f8a3c5b1d7e9f2a4c",
      "created_at": "2026-10-07T14:10:27Z",
      "updated_at": "2026-10-07T14:10:27Z",
      "status": {
        "time_period": {"start": "2026-10-01T00:00:00Z", "end": "2026-11-01T00:00:00Z"},
        "evaluated_at": "2026-10-07T15:00:04Z",
        "as_of": "2026-10-07T15:00:00Z",
        "data_through": "2026-10-07T14:00:00Z",
        "currency": "USD",
        "amount": "1000",
        "actual_spend": "248.731250000000",
        "forecast_spend": "1155.164285714286",
        "estimated": true,
        "thresholds": [
          {"name": "warn", "state": "ok", "target_amount": "800", "observed": "248.731250000000"}
        ]
      }
    }
  ]
}
```

Budgets and notification channels are the two resources. A budget's thresholds name channels by
ID, so create channels first.

## Errors

Errors use the [problem details](https://www.rfc-editor.org/rfc/rfc9457) format, `application/problem+json`. `detail` says what went wrong, and a validation error lists each problem in `errors` with the `location` of the field:

```json
{
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "validation failed",
  "errors": [
    {
      "location": "body",
      "message": "expected required property name to be present",
      "value": {}
    }
  ]
}
```

Every response carries an `X-Request-ID` header. Include it when you contact support about a request.

## Operations

| Method   | Path                                                                                                                           | Description                                             |
| -------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| `GET`    | [`/v1/budgets`](/budgets/api/budgets/list-budgets)                                                                             | List budgets                                            |
| `POST`   | [`/v1/budgets`](/budgets/api/budgets/create-budget)                                                                            | Create a budget                                         |
| `GET`    | [`/v1/budgets/{budget_id}`](/budgets/api/budgets/get-budget)                                                                   | Get a budget and the status of its current window       |
| `PUT`    | [`/v1/budgets/{budget_id}`](/budgets/api/budgets/update-budget)                                                                | Replace a budget                                        |
| `DELETE` | [`/v1/budgets/{budget_id}`](/budgets/api/budgets/delete-budget)                                                                | Delete a budget and its history                         |
| `GET`    | [`/v1/budgets/{budget_id}/notifications`](/budgets/api/budgets/list-budget-notifications)                                      | List a budget's alerts and their delivery, newest first |
| `GET`    | [`/v1/budgets/{budget_id}/windows`](/budgets/api/budgets/list-budget-windows)                                                  | List a budget's past and current windows, newest first  |
| `GET`    | [`/v1/notification_channels`](/budgets/api/notification-channels/list-notification-channels)                                   | List notification channels                              |
| `POST`   | [`/v1/notification_channels`](/budgets/api/notification-channels/create-notification-channel)                                  | Create a notification channel                           |
| `GET`    | [`/v1/notification_channels/{channel_id}`](/budgets/api/notification-channels/get-notification-channel)                        | Get a notification channel                              |
| `DELETE` | [`/v1/notification_channels/{channel_id}`](/budgets/api/notification-channels/delete-notification-channel)                     | Delete a notification channel                           |
| `POST`   | [`/v1/notification_channels/{channel_id}/resend_confirmation`](/budgets/api/notification-channels/resend-channel-confirmation) | Send an email channel's confirmation link again         |
| `POST`   | [`/v1/notification_channels/{channel_id}/rotate_secret`](/budgets/api/notification-channels/rotate-channel-secret)             | Replace a webhook channel's signing secret              |

## OpenAPI schema

Download the schema as [JSON](/budgets/openapi.json) or [YAML](/budgets/openapi.yaml) to generate a client or import the API into a tool such as Postman.