> For the complete documentation index, see [llms.txt](https://aura-monitoring.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aura-monitoring.gitbook.io/docs/developers/api-reference.md).

# REST API Reference

Automate monitor management from CI pipelines, scripts, Terraform, or any HTTP-capable tool. The REST API exposes the same data you can see in the dashboard, scoped to a single organization.

An interactive reference with full request/response schemas lives at [**/docs/api**](https://auramonitoring.com/docs/api). You can paste a bearer token into the **Authorize** button there and issue real requests from the browser.

## Authentication

Every request requires a bearer token:

```
Authorization: Bearer aura_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Tokens are organization-scoped

Each API token belongs to exactly one organization. The token grants access only to monitors, heartbeats, incidents, and integrations inside that organization — switching organizations in the dashboard does not change what the token can see.

If you belong to multiple organizations and need API access to more than one, create a separate token in each organization.

### Creating a token

{% stepper %}
{% step %}

### Switch to the right organization

Use the organization switcher in the dashboard to select the organization you want the token to access. The token will be bound to whichever organization is active when you create it.
{% endstep %}

{% step %}

### Open Account → API Tokens

Click **Create token**, pick a label (for example, "CI deploys"), and pick a scope:

* **Read & write** — `GET` requests plus the write actions your organization role allows (see [Token permissions](#token-permissions) below).
* **Read only** — `GET` requests only; any mutation returns `403`.

A token can never do more than you can. If your organization role is **Viewer** (read-only), the **Read & write** option is unavailable and your token is limited to read access.
{% endstep %}

{% step %}

### Copy the token immediately

We never show it again — if you lose it you'll need to revoke and recreate.
{% endstep %}
{% endstepper %}

### Revoking

In the tokens list, click the trash icon next to any token. Revocation is immediate — requests using that token will start returning `401` within 30 seconds (we cache successful lookups briefly for performance).

## Token permissions

A token acts on your behalf, so it follows the **same permission rules as the dashboard**. A **Read & write** token can only perform a write if your organization role allows it — otherwise the request returns `403`.

| Action                                  | Who can do it                                    |
| --------------------------------------- | ------------------------------------------------ |
| Read anything (`GET`)                   | Any organization role, including **Viewer**      |
| Create or update a monitor or heartbeat | Organization **Owner**, **Admin**, or **Member** |
| Delete a monitor or heartbeat           | Organization **Owner** or **Admin**              |
| Resolve an incident                     | Organization **Owner**, **Admin**, or **Member** |

For monitors and heartbeats that belong to a **team**, you also need to be a member of that team to create or change them — exactly as in the dashboard. See [Teams](/docs/teams-and-organizations/teams.md#how-organization-and-team-roles-interact) for how organization and team roles interact.

{% hint style="info" %}
If a token used to be able to write and suddenly returns `403`, check whether your organization role changed. Permissions are evaluated on every request, so a downgrade takes effect immediately.
{% endhint %}

## Base URL

```
https://vijdplkdpkvdtybzjtgq.supabase.co/functions/v1/api-v1
```

## Rate limits

Per token:

| Window   | Limit         |
| -------- | ------------- |
| 1 minute | 60 requests   |
| 1 hour   | 1000 requests |

When you exceed either window you'll get `429 Too Many Requests` with a `Retry-After` header containing the number of seconds until the window resets. Successful responses expose `X-RateLimit-Remaining-Minute` and `X-RateLimit-Remaining-Hour`.

## Error envelope

All non-2xx responses return:

```json
{
  "error": {
    "code": "not_found",
    "message": "Monitor not found",
    "request_id": "req_01HV2S..."
  }
}
```

Quote the `request_id` when asking support to investigate a failed call.

Known error codes:

| Code             | HTTP | When                                                     |
| ---------------- | ---- | -------------------------------------------------------- |
| `bad_request`    | 400  | Malformed JSON or failed validation                      |
| `unauthorized`   | 401  | Missing, invalid, or revoked token                       |
| `forbidden`      | 403  | Token scope or your organization role forbids the action |
| `not_found`      | 404  | Resource missing or not owned by caller                  |
| `conflict`       | 409  | Violates plan limits or DB constraints                   |
| `rate_limited`   | 429  | Hit per-minute or per-hour cap                           |
| `internal_error` | 500  | Something unexpected — please report                     |

## Pagination

List endpoints return cursor-paginated responses:

```json
{
  "data": [ /* ... */ ],
  "next_cursor": "eyJpZCI6ImFiYyIsImNyZWF0ZWRfYXQiOiIyMDI2LS4uLiJ9"
}
```

Pass `next_cursor` back as the `cursor` query parameter to get the next page. When `next_cursor` is `null` you've reached the end. The `limit` parameter accepts 1–100, default 50.

## Endpoints

| Resource     | Endpoints                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------- |
| Monitors     | `GET/POST /monitors`, `GET/PATCH/DELETE /monitors/{id}`                                      |
| Checks       | `GET /monitors/{id}/checks`, `GET /checks?monitor_id=…`                                      |
| Heartbeats   | `GET/POST /heartbeats`, `GET/PATCH/DELETE /heartbeats/{id}`, `GET /heartbeats/{id}/ping-url` |
| Incidents    | `GET /incidents`, `GET /incidents/{id}`, `POST /incidents/{id}/resolve`                      |
| Integrations | `GET /integrations` (read-only)                                                              |

Full request and response schemas live in the [interactive docs](https://auramonitoring.com/docs/api).

## Examples

### List your monitors

```bash
curl -s \
  -H "Authorization: Bearer $AURA_TOKEN" \
  https://vijdplkdpkvdtybzjtgq.supabase.co/functions/v1/api-v1/monitors
```

### Create a monitor

The new monitor is created in the token's organization automatically — you don't pass an organization id in the body.

```bash
curl -s -X POST \
  -H "Authorization: Bearer $AURA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api.example.com",
    "url": "https://api.example.com/health",
    "check_interval": 60
  }' \
  https://vijdplkdpkvdtybzjtgq.supabase.co/functions/v1/api-v1/monitors
```

### Resolve an incident

```bash
curl -s -X POST \
  -H "Authorization: Bearer $AURA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "resolution_notes": "Restart fixed it" }' \
  https://vijdplkdpkvdtybzjtgq.supabase.co/functions/v1/api-v1/incidents/INCIDENT_ID/resolve
```

### Get the ping URL for a heartbeat

```bash
curl -s \
  -H "Authorization: Bearer $AURA_TOKEN" \
  https://vijdplkdpkvdtybzjtgq.supabase.co/functions/v1/api-v1/heartbeats/HEARTBEAT_ID/ping-url
```

Use the returned `url` value as the endpoint your cron job POSTs to.

## Security notes

* Tokens are sensitive. Store them in your CI secret store, a password manager, or a dedicated secrets service — never in source control.
* A token grants access only to the organization it was issued in. Rotate tokens whenever an employee leaves the organization or a device may be compromised.
* Integration credentials (Slack webhooks, Telegram bot tokens, etc.) are **never** returned through the API. The `/integrations` endpoint exposes only the platform and the URL host for identification.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://aura-monitoring.gitbook.io/docs/developers/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.