# Using the API


Using our easy-to-use REST API you can administer projects, errors, and performance monitoring data. All endpoints are also available through the [Flare CLI](/docs/flare/general/using-the-cli).

## Authentication

There are two ways to authenticate with the Flare API: personal access tokens and legacy API tokens. Personal access tokens are the recommended option for any new integration. Every request should include an `Accept: application/json` header.

### Personal access tokens (recommended)

Personal access tokens are scoped to the teams and projects you choose, and to one or more of the `read`, `write`, and `admin` scopes. You can revoke them individually at any time from your account settings.

Create one in [your account settings](/account/personal-access-tokens). Personal access tokens are sent as a Bearer token in the Authorization header.

```shellscript
curl "https://flareapp.io/api/projects" \
     -H 'Authorization: Bearer <token>' \
     -H 'Accept: application/json'
```

**Scopes**

- `read` — Read errors, logs, traces, projects, and team data.
- `write` — Resolve, snooze, comment, upload sourcemaps, change settings.
- `admin` — Manage team membership, billing, projects, and API keys.

Requests made with a token that is missing the required scope return a `403` response.

### Legacy API tokens

Legacy API tokens predate personal access tokens. They grant full access to every team and project the issuing user belongs to and cannot be scoped further. We still support them so existing integrations keep working, but new integrations should use a personal access token instead. Once you revoke all of your legacy tokens, the legacy tokens screen disappears from your account settings.

Create one in [your account settings](/account/api-tokens). Legacy tokens can be sent either as a Bearer token or as an `api_token` query parameter:

```shellscript
curl "https://flareapp.io/api/projects?api_token=<token>" \
     -H 'Accept: application/json'
```

```shellscript
curl "https://flareapp.io/api/projects" \
     -H 'Authorization: Bearer <token>' \
     -H 'Accept: application/json'
```

## Pagination

All paginated endpoints follow the JSON:API pagination specification. Use `page[number]` and `page[size]` query parameters to navigate through results. All paginated responses include a `meta` object with `current_page`, `total`, `per_page`, and `last_page` fields.

```shellscript
curl "https://flareapp.io/api/projects?page[number]=2&page[size]=15" \
     -H 'Authorization: Bearer <token>' \
     -H 'Accept: application/json'
```

## Using an API client

### OpenAPI

We provide an [OpenAPI](https://swagger.io/specification/) specification for our API.

<div class="docs-link-button-row docs-link-button-row-spaced">
    <a href="/api/openapi.yaml" class="docs-link-button button-secondary rounded-12">Download OpenAPI spec</a>
    <a href="/api-docs" class="docs-link-button button-secondary rounded-12">Browse API reference</a>
</div>

### Postman

Postman is a platform for API development that offers [a free application](https://www.postman.com/downloads) to easily
make API requests.

To easily use our API with Postman, import [this JSON file](/api/openapi.yaml) which contains
presets for all available endpoints.

### Paw

Paw is a highly polished, paid API tool for Mac. You can download a free trial [here](https://paw.cloud).

To easily use our API with Paw, open [this file](/api/openapi.yaml) which contains presets for all available
endpoints.

## Endpoints

We've got a special page with all the API endpoints and their documentation. You can find it [here](/api-docs).

### Projects

- **`GET /api/projects`** — List all projects.
- **`POST /api/projects`** — Create a new project.
- **`GET /api/projects/{project_id}`** — Get a single project.

### Errors

- **`GET /api/projects/{project_id}/errors`** — List errors in a project. Supports filtering by status, exception class, file, stage, log level, and date ranges.
- **`GET /api/projects/{project_id}/error-count`** — Get the number of unique errors in a date range. Accepts ISO 8601 dates (e.g. `2026-02-20T00:00:00Z`).
- **`GET /api/projects/{project_id}/error-occurrence-count`** — Get the total number of error occurrences in a date range. Accepts ISO 8601 dates (e.g. `2026-02-20T00:00:00Z`).
- **`GET /api/errors/{error_id}/occurrences`** — List all occurrences of an error.
- **`GET /api/error-occurrences/{occurrence_id}`** — Get a single occurrence with full details.
- **`POST /api/errors/{error_id}/resolve`** — Resolve an error.
- **`POST /api/errors/{error_id}/open`** — Reopen an error.
- **`POST /api/errors/{error_id}/snooze`** — Snooze an error.
- **`POST /api/errors/{error_id}/unsnooze`** — Unsnooze an error.

### Performance Monitoring

Performance monitoring endpoints let you retrieve aggregated metrics, time series data, and traces for your application's routes, queries, jobs, commands, external HTTP requests, views, and Livewire components. Monitoring data is retained for 30 days.

All monitoring endpoints accept a `filter[interval]` parameter to control the time window: `1h`, `3h`, `6h`, `24h` (default), `48h`, `7d`, `14d`, or `custom:START,END` with ISO 8601 dates (e.g. `custom:2026-02-01T00:00:00Z,2026-02-20T23:59:59Z`).

The `{type}` parameter accepts: `routes`, `queries`, `jobs`, `commands`, `external-http`, `views`, `livewire-components`.

- **`GET /api/projects/{project_id}/monitoring/summary`** — Get the monitoring dashboard summary with high-level metrics and trends for routes, jobs, commands, and queries, plus the top-10 slowest routes and queries.

```shellscript
curl "https://flareapp.io/api/projects/1/monitoring/summary?filter[interval]=24h" \
     -H 'Authorization: Bearer xyz123' \
     -H 'Accept: application/json'
```

- **`GET /api/projects/{project_id}/monitoring/{type}`** — List aggregations by type. Returns a paginated, filterable, sortable list. Supports `filter[search]`, `filter[p95:>=]`, `filter[average:>=]`, `filter[count:>=]`, `filter[error_rate:>=]`, and `sort` parameters.

```shellscript
curl "https://flareapp.io/api/projects/1/monitoring/routes?filter[interval]=7d&sort=-p95&page[size]=15" \
     -H 'Authorization: Bearer xyz123' \
     -H 'Accept: application/json'
```

- **`GET /api/projects/{project_id}/monitoring/{type}/time-series`** — Get time series data for graphing. Precision is auto-selected based on the interval: minute for ≤24h, hour for ≤14d, day otherwise.

```shellscript
curl "https://flareapp.io/api/projects/1/monitoring/routes/time-series?filter[interval]=24h" \
     -H 'Authorization: Bearer xyz123' \
     -H 'Accept: application/json'
```

- **`GET /api/aggregations/{type}/{uuid}`** — Get a single aggregation with detailed metrics, trends, and relationship links. Use the `include` parameter to load additional data: `parents`, `children`.

```shellscript
curl "https://flareapp.io/api/aggregations/routes/abc-123?include=parents,children" \
     -H 'Authorization: Bearer xyz123' \
     -H 'Accept: application/json'
```

- **`GET /api/aggregations/{type}/{uuid}/traces`** — List traces for an aggregation. Uses a fixed 6-hour lookback window. Supports sorting by `slowest` (default), `fastest`, `latest`, or `oldest`.

```shellscript
curl "https://flareapp.io/api/aggregations/routes/abc-123/traces?sort=slowest&page[size]=10" \
     -H 'Authorization: Bearer xyz123' \
     -H 'Accept: application/json'
```

- **`GET /api/traces/{traceId}`** — Get the full span tree for a trace, including all span events, resources, and contexts.

```shellscript
curl "https://flareapp.io/api/traces/abc123def456" \
     -H 'Authorization: Bearer xyz123' \
     -H 'Accept: application/json'
```

### Teams

- **`GET /api/teams/{team_id}`** — Get a team and its members.
- **`DELETE /api/teams/{team_id}/users/{user_id}`** — Remove a user from a team.

### User

- **`GET /api/me`** — Get the currently authenticated user and their teams.