> ## Documentation Index
> Fetch the complete documentation index at: https://docs.larm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Authenticate and interact with the Larm API

## Base URL

```
https://app.larm.dev/api/v1
```

## Authentication

All API requests require a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://app.larm.dev/api/v1/monitors \
  -H "Authorization: Bearer larm_api_..."
```

### Creating an API key

1. Go to **Dashboard > Settings > API Keys**
2. Click **Create API key**
3. Choose permissions for each resource (monitors, status pages, alert channels)
4. Copy the key — it's only shown once

API keys use the format `larm_api_<base64-payload><crc32>`.

### Permissions

Each API key has a permission level per resource:

| Resource       | Levels                       |
| -------------- | ---------------------------- |
| Monitors       | `none`, `read`, `read_write` |
| Status pages   | `none`, `read`, `read_write` |
| Alert channels | `none`, `read`, `read_write` |

<Note>
  Full API access (read and write) is available on all plans, including Free.
</Note>

## Rate limits

| Operation | Limit            |
| --------- | ---------------- |
| Read      | 120 requests/min |
| Write     | 30 requests/min  |
| Stats     | 30 requests/min  |

Limits are per API key. Rate limit headers are included on every response:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `x-ratelimit-limit`     | Maximum requests allowed in the window    |
| `x-ratelimit-remaining` | Requests remaining in the current window  |
| `x-ratelimit-reset`     | Unix timestamp when the window resets     |
| `retry-after`           | Seconds until you can retry (only on 429) |

## Error format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": {
    "type": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}
```

### Standard error codes

| Status | Type              | Description                                    |
| ------ | ----------------- | ---------------------------------------------- |
| 401    | `invalid_api_key` | Missing, invalid, or revoked API key           |
| 403    | `forbidden`       | API key lacks the required permission          |
| 429    | `rate_limited`    | Too many requests — check `retry-after` header |

The [heartbeat endpoint](/api-reference/heartbeat) uses token-based authentication (no API key needed). All other endpoints require an API key.