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

# API Overview

> Integrate Upmetr into your workflows via the REST API

# API Reference

Upmetr exposes a RESTful API for managing cloud accounts, monitors, incidents, costs, and more. All endpoints are available under `/api/v1`.

## Base URL

```
https://app.upmetr.com/api/v1
```

## Authentication

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

```bash theme={null}
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://app.upmetr.com/api/v1/resources
```

### Getting a Token

Authenticate via the login endpoint:

```bash theme={null}
curl -X POST https://app.upmetr.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'
```

Response:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1...",
  "refresh_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer"
}
```

### Refreshing Tokens

Access tokens expire after 30 minutes. Use the refresh endpoint:

```bash theme={null}
curl -X POST https://app.upmetr.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1..."}'
```

## Rate Limits

| Scope                    | Limit              |
| ------------------------ | ------------------ |
| Per user                 | 60 requests/minute |
| Per IP (unauthenticated) | 20 requests/minute |

When rate limited, the API returns `429 Too Many Requests` with a `Retry-After` header.

## Error Format

All errors follow a consistent format:

```json theme={null}
{
  "detail": "Error description"
}
```

### HTTP Status Codes

| Code  | Meaning                                 |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Created                                 |
| `400` | Bad request (validation error)          |
| `401` | Unauthorized (invalid or expired token) |
| `403` | Forbidden (insufficient permissions)    |
| `404` | Not found                               |
| `429` | Rate limited                            |
| `500` | Internal server error                   |

## Organization Context

All API calls are scoped to the **current organization** of the authenticated user. The organization is determined by the JWT token — you don't need to pass an `org_id` parameter.

If a user belongs to multiple organizations, they select the active org during login via the `select-org` endpoint.

## Interactive Documentation

Upmetr also provides interactive API documentation:

* **Swagger UI** — `https://app.upmetr.com/docs`
* **ReDoc** — `https://app.upmetr.com/redoc`
* **OpenAPI Spec** — `https://app.upmetr.com/openapi.json`

## Endpoint Categories

| Category            | Description                                     | Endpoints |
| ------------------- | ----------------------------------------------- | --------- |
| **Auth**            | Login, register, refresh, MFA, magic link       | 15+       |
| **Users**           | User management, invitations, avatars           | 10+       |
| **Cloud Accounts**  | CRUD, test connection, discover resources       | 7         |
| **Resources**       | List, filter, actions (start/stop/reboot)       | 8         |
| **Uptime Monitors** | CRUD, metrics, daily uptime, maintenance        | 9         |
| **Incidents**       | List, acknowledge, resolve, bulk actions        | 8         |
| **Costs**           | Summary, by-service, by-account, forecast, sync | 7         |
| **Budgets**         | CRUD, status                                    | 6         |
| **Alert Rules**     | CRUD, toggle, overrides                         | 7         |
| **Notifications**   | Channels, rules, preferences, in-app            | 15+       |
| **Infra Agents**    | CRUD, token regeneration, install script        | 7         |
| **Infra Metrics**   | Summary, per-agent metrics, containers          | 6         |
| **Status Pages**    | Global and client status pages                  | 10+       |
| **Billing**         | Plans, checkout, portal, invoices               | 10+       |
| **Audit Logs**      | Security event trail                            | 4         |
| **Platform Admin**  | Organization and plan management                | 7         |

Browse the full endpoint reference in the sidebar.