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

# Specter API: Query Sites, Sensors, Workflows, and Alerts

> Overview of the Specter REST/JSON API: what you can query, how requests are structured, and how cursor-based pagination works across list endpoints.

## What you can do

<CardGroup cols={2}>
  <Card title="Sites" icon="building">
    List the sites in your organization, including each site's time zone.
  </Card>

  <Card title="Sensors" icon="sensor">
    List sensors, optionally filtered to a single site.
  </Card>

  <Card title="Workflows" icon="diagram-project">
    List the workflows configured for a site and the sensors active in each one.
  </Card>

  <Card title="Alert summaries" icon="chart-column">
    Count alert events by outcome (pending, resolved, dismissed) over hourly, daily, or weekly buckets.
  </Card>
</CardGroup>

## Making requests

All endpoints live under the `/api/v1` path, accept `GET` requests, and return JSON. Authenticate every request with an API key passed as a bearer token. See [Authentication](/api-reference/authentication).

```bash theme={null}
curl "https://staging.specter.co/api/v1/sites" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Pagination

The list endpoints (`/sites`, `/sensors`, and `/workflows`) use cursor-based pagination.

<ParamField query="pageSize" type="integer">
  Maximum number of items to return. For `/sites`, the default and maximum are both 100.
</ParamField>

<ParamField query="pageToken" type="string">
  The `nextPageToken` value from a previous response. Omit it to fetch the first page.
</ParamField>

Each list response includes a `nextPageToken`. Pass it as `pageToken` on your next request to get the following page, and continue until you have retrieved every item.

```bash theme={null}
curl "https://staging.specter.co/api/v1/sensors?pageSize=50&pageToken=NEXT_PAGE_TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Alert summary limits

`GET /api/v1/alerts/summary` takes inclusive `startDate` and `endDate` values (`YYYY-MM-DD`) in each site's local calendar. Granularity defaults to `daily`. Ranges are limited to:

* **Hourly:** up to 31 days
* **Daily or weekly:** up to 366 days
* **Any granularity:** at most 10,000 rows

Requests over these limits return `400` with the `report_too_large` error code. In every bucket, `pendingEventCount + resolvedEventCount + dismissedEventCount` equals `alertEventCount`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.