> ## Documentation Index
> Fetch the complete documentation index at: https://pulse-41cf5b0d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PulseGuard REST API Reference

> The PulseGuard API lets you manage monitors, retrieve events, and trigger checks programmatically. Authenticate with a Bearer token.

The PulseGuard REST API gives you full programmatic control over your monitors, status pages, and alert history. Every request is authenticated with a scoped API key, every response is JSON, and every endpoint lives under the single base URL below.

## Base URL

```
https://app.pulseguard.io
```

All paths in this reference are relative to this base URL. For example, the full URL for listing monitors is `https://app.pulseguard.io/api/cli/monitors`.

## Authentication

Pass your API key as a Bearer token in every request:

```
Authorization: Bearer pg_live_your_api_key_here
```

Read the [Authentication guide](/api/authentication) for details on creating keys, choosing scopes, and rotating credentials.

## Response format

All responses are `application/json`. Successful responses return a top-level object containing the requested resource or list. Error responses return a single `error` field describing what went wrong.

```json theme={null}
{
  "error": "name is required"
}
```

## Available endpoints

<Info>
  Monitor endpoints under `/api/cli/monitors` require a Bearer token. The API key management endpoints (`/api/cli/api-keys`) use your dashboard session cookie and are intended for use through the PulseGuard dashboard. The latency heatmap and workspace export endpoints also use dashboard session authentication. Badge, RSS, and widget endpoints are public and unauthenticated.
</Info>

| Method   | Path                                | Auth                 | Description                    |
| -------- | ----------------------------------- | -------------------- | ------------------------------ |
| `GET`    | `/api/cli/monitors`                 | Bearer token         | List all monitors              |
| `POST`   | `/api/cli/monitors`                 | Bearer token (write) | Create a monitor               |
| `GET`    | `/api/cli/monitors/:id`             | Bearer token         | Get a monitor                  |
| `PUT`    | `/api/cli/monitors/:id`             | Bearer token (write) | Update a monitor               |
| `DELETE` | `/api/cli/monitors/:id`             | Bearer token (write) | Delete a monitor               |
| `POST`   | `/api/cli/monitors/:id/trigger`     | Bearer token         | Trigger an immediate check     |
| `GET`    | `/api/cli/monitors/:id/events`      | Bearer token         | List monitor events            |
| `GET`    | `/api/cli/api-keys`                 | Session cookie       | List API keys                  |
| `POST`   | `/api/cli/api-keys`                 | Session cookie       | Create an API key              |
| `DELETE` | `/api/cli/api-keys/:id`             | Session cookie       | Delete an API key              |
| `GET`    | `/api/monitors/:id/latency-heatmap` | Session cookie       | Get latency heatmap data       |
| `GET`    | `/api/workspace/export`             | Session cookie       | Export workspace configuration |
| `GET`    | `/api/badge/:slug`                  | Public               | Get status badge SVG           |
| `GET`    | `/api/feeds/:slug/rss`              | Public               | Get RSS feed for a status page |
| `GET`    | `/api/widget/:slug/status`          | Public               | Get status page widget data    |

## Error responses

PulseGuard uses standard HTTP status codes. When a request fails, the response body always contains an `error` field with a human-readable message.

| Status                      | Meaning                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `400 Bad Request`           | A required field is missing or a value is invalid                                      |
| `401 Unauthorized`          | The API key is missing, malformed, or expired                                          |
| `403 Forbidden`             | The API key is valid but lacks the `write` scope required by this endpoint             |
| `404 Not Found`             | The requested resource does not exist or belongs to another account                    |
| `422 Unprocessable Entity`  | The request is well-formed but cannot be executed (e.g. triggering a non-HTTP monitor) |
| `500 Internal Server Error` | An unexpected error occurred on the server                                             |

**Example error body:**

```json theme={null}
{
  "error": "name is required"
}
```

<Tip>
  When debugging `401` errors, double-check that you are sending the `Authorization` header and that the key has not expired. For `403` errors, check that your key has the `write` scope if you are trying to create, update, or delete a resource.
</Tip>