# REST API

> https://docs.errora.org/en/api/rest

Everything the dashboard does is a call to `/api/v1`. The live OpenAPI schema is at
`GET /api/schema/`, with Swagger UI at `/api/docs/`.

## Authentication

Two credential types, same header:

```http
Authorization: Bearer <jwt_access_token>     # a signed-in user
Authorization: Bearer errora_pat_…           # a personal access token (CI, scripts, MCP)
```

Get a JWT with `POST /auth/login` or `POST /auth/otp/verify`, refresh it with
`POST /auth/refresh`. For anything long-lived use a
[personal access token](/en/account/tokens).

Every endpoint checks a **capability** (`project:read`, `issue:write`, `org:billing`, …), not
a role name — see [Roles](/en/account/organizations#roles--permissions).

## Conventions

- IDs are UUIDs. Cron monitors are also addressable by **slug**.
- List endpoints take `limit`/`offset`, and mostly `stats_period` (`1h`, `24h`, `7d`, `14d`,
  `30d`) plus `environment`.
- Text search is `q`.
- Times are ISO-8601 UTC.
- Errors are `{"detail": "…"}` with the usual status codes: `400` validation, `401`
  unauthenticated, `403` missing capability, `404` not found or not yours, `429` rate limited.

## Endpoint map

| Area | Endpoints |
| --- | --- |
| Auth | `POST /auth/start`, `/auth/login`, `/auth/otp/request`, `/auth/otp/verify`, `/auth/refresh`, `/auth/logout`, `/auth/password`, `/auth/totp/setup\|enable\|disable`, `GET /auth/me` |
| Tokens | `GET/POST /auth/tokens`, `DELETE /auth/tokens/{id}` |
| Organizations | `GET/POST /organizations`, `GET/PATCH/DELETE /organizations/{id}`, `GET .../members`, `PATCH .../members/{id}`, `GET .../invites`, `POST .../invite`, `GET /invites/preview/{token}`, `POST /invites/accept` |
| Projects | `GET/POST /organizations/{id}/projects`, `GET/PATCH/DELETE .../projects/{id}`, `GET .../projects/stats`, `GET/POST .../projects/{id}/keys` |
| Issues | `GET /projects/{id}/issues`, `GET .../issues/{id}`, `POST .../issues/{id}/resolve\|ignore\|archive\|bookmark\|assign`, `GET .../issues/trends`, `GET .../issues/{id}/series`, `GET .../events/{event_id}` |
| Issue tracking | `GET/POST .../issues/{id}/external-issues`, `GET .../external-issues/search`, `GET .../issues/{id}/repositories` |
| Performance | `GET /projects/{id}/transactions`, `GET .../transactions/{id}` |
| Logs | `GET /projects/{id}/logs`, `GET .../logs/{id}`, `GET .../logs/attribute-keys` |
| Replays | `GET /projects/{id}/replays`, `GET .../replays/{replay_id}`, `GET .../replays/{replay_id}/events` |
| Cron monitors | `GET/POST /projects/{id}/monitors`, `GET/PATCH/DELETE .../monitors/{slug}`, `GET .../monitors/{slug}/checkins\|stats`, `GET .../monitors/overview` |
| Uptime | `GET/POST /projects/{id}/uptime-monitors`, `GET/PATCH/DELETE .../uptime-monitors/{id}`, `GET .../checks\|stats`, `POST .../check-now`, `GET .../uptime-monitors/overview` |
| User feedback | `GET/POST /projects/{id}/feedback`, `GET/PATCH/DELETE .../feedback/{id}`, `GET .../feedback/summary`, `GET /issues/{id}/feedback` |
| Profiling | `GET /projects/{id}/profiles`, `GET .../profiles/{id}`, `GET .../profiles/{id}/flamegraph`, `GET .../profiles/functions\|overview` |
| Metrics | `GET /projects/{id}/metrics`, `GET .../metrics/series\|summary\|tags` |
| AI monitoring | `GET /projects/{id}/insights/agents`, `.../insights/agents/runs`, `.../insights/agents/runs/{trace_id}`, `.../insights/mcp` |
| Source maps | `GET/POST /projects/{id}/release-files`, `GET/DELETE .../release-files/{id}` |
| Dashboards | `GET /dashboards/catalog`, `GET/POST /organizations/{id}/dashboards`, `GET/PATCH/DELETE .../dashboards/{id}`, `POST .../widgets`, `PATCH .../widgets/reorder`, `PATCH/DELETE .../widgets/{id}`, `GET .../widgets/{id}/data` |
| Integrations | `GET/POST /organizations/{id}/integrations`, `POST .../integrations/{id}/sync`, `GET .../integrations/{id}/repositories` |
| AI | `POST /projects/{id}/issues/{id}/autofix`, `GET/POST /organizations/{id}/ai-configs`, `PATCH/DELETE .../ai-configs/{id}` |
| Alerts | `GET/POST /organizations/{id}/channels`, `PATCH/DELETE .../channels/{id}`, `GET .../channels/template-meta`, `POST .../channels/preview`, `POST .../channels/{id}/test`, `GET/POST .../alert-rules`, `POST .../chat-links/start` |
| Billing | `GET /pricing`, `GET /organizations/{id}/usage`, `GET .../wallet`, `GET .../wallet/transactions`, `GET/POST/PATCH/DELETE .../balance-alerts` |
| Payments | `GET /payment-gateways`, `POST /organizations/{id}/wallet/top-up`, `GET .../payments` |

Outside `/api/v1`: the [ingestion endpoints](/en/api/ingest) and `POST /mcp`
([MCP server](/en/products/mcp)).

## Example

```bash
# Sign in
ACCESS=$(curl -s -X POST "$ERRORA/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"09121234567","password":"…"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["access"])')

# Unresolved issues in the last 24h
curl -s -H "Authorization: Bearer $ACCESS" \
  "$ERRORA/api/v1/projects/$PROJECT_ID/issues?status=unresolved&stats_period=24h&limit=10"

# Resolve one
curl -s -X POST -H "Authorization: Bearer $ACCESS" \
  "$ERRORA/api/v1/projects/$PROJECT_ID/issues/$ISSUE_ID/resolve"
```