Docs / Team, API and appBrowse

API and MCP

The API lets your own tools work with your workspace: list and change monitors, read uptime, acknowledge incidents, open maintenance from CI. Claude, Cursor, VS Code and other AI assistants connect over MCP, signing in with your Heedery account or with the same tokens. Every endpoint, field and example is in the API reference.

On this page
  1. Plans and access
  2. Create a token
  3. What you can do
  4. Claude, Cursor, VS Code and other assistants (MCP)
  5. Errors and limits

Plans and access

Plan/Pro and up. Write tokens from Team and up

A read token lists monitors, incidents, maintenance, deploys and metrics. A write token can also add, change, pause and delete monitors, acknowledge and comment on incidents, schedule maintenance and report deploys.

Create a token

  1. 1.
    Go to Settings then Integrations then API.
  2. 2.
    Name the token after the tool that will use it, pick its scope and press Create token.
  3. 3.
    Copy it now. It starts with hda_ and is not shown again.

A workspace can have 10 tokens. Owners and admins create, rotate and delete them. A token works while the person who made it is still an owner or admin of the workspace.

The API tokens panel in Settings, Integrations
Settings → Integrations, the API section.

What you can do

Send the token in the Authorization header. Everything answers JSON under https://heedery.com/api/v1.

Monitors
List with filters, add, change, pause, resume and delete; uptime, average and p95 response time per day.
Incidents
List and read with the timeline and evidence; acknowledge and comment. endReason tells a pause (paused, or plan when the plan paused the monitor) from a recovery; no recovery alert goes out for a pause, and status page subscribers who were told of the outage hear that monitoring is paused.
Maintenance
Schedule, change, end early and delete windows. Useful around a deploy.
Deploys
List and report deploys, the same markers the CI webhook adds.
Status
Every monitor with its state in one call, for a wall dashboard.
Which monitors are down
curl https://heedery.com/api/v1/monitors?status=down \
  -H "Authorization: Bearer hda_…"
Maintenance for the next deploy
curl -X POST https://heedery.com/api/v1/maintenance \
  -H "Authorization: Bearer hda_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-2026-11-10-1" \
  -d '{ "title": "Deploy", "monitorIds": ["cm3…"], "endsAt": "2026-11-10T10:30:00Z" }'

NoteThe full description is also a machine-readable OpenAPI 3.1 file at /api/v1/openapi.json, ready for Postman or a client generator.

Claude, Cursor, VS Code and other assistants (MCP)

Heedery runs an MCP server at https://heedery.com/api/mcp. Connect it and ask in plain words: “what is down right now?”, “uptime of the shop this month”, “put the shop in maintenance for an hour”. Read access gets the reading tools; write access also gets the ones that change things.

claude.ai (and Claude Desktop and mobile) sign in with your Heedery account, no token needed:

  1. 1.
    In claude.ai open Settings then Connectors then Add custom connector.
  2. 2.
    Name it Heedery and paste https://heedery.com/api/mcp as the URL.
  3. 3.
    Press Connect, sign in to Heedery if asked, pick the workspace and read or write, and press Allow.

Claude Code, Cursor and VS Code sign in the same way: add the server by its address alone, with no token. Claude Code asks when you run /mcp and choose Authenticate; Cursor when you press Connect next to the server in its MCP settings; VS Code when the server starts. Heedery opens in the browser, you allow it, and the code goes back to the app. The page names where it goes (Cursor on this device, or localhost) so you can tell it is the app you just started.

Claude Code
claude mcp add --transport http heedery https://heedery.com/api/mcp
Cursor, in mcp.json
{
  "mcpServers": {
    "heedery": { "url": "https://heedery.com/api/mcp" }
  }
}
VS Code, in .vscode/mcp.json
{
  "servers": {
    "heedery": { "type": "http", "url": "https://heedery.com/api/mcp" }
  }
}

You can connect a workspace you own or run as an admin on Pro and above; write access needs Team. Each app shows under Settings then Integrations then API as a connected app, with Revoke. Other MCP clients that sign in with OAuth work like this too.

Scripts, CI and assistants that do not sign in take an API token in a header instead:

Claude Code with a token
claude mcp add --transport http heedery https://heedery.com/api/mcp \
  --header "Authorization: Bearer hda_…"
Cursor with a token, in mcp.json
{
  "mcpServers": {
    "heedery": {
      "url": "https://heedery.com/api/mcp",
      "headers": { "Authorization": "Bearer hda_…" }
    }
  }
}

Errors and limits

401
The token is missing or unknown.
403
The plan does not include this (plan_required) or the token is read-only (scope_required).
404
No such object in this workspace.
422
The request does not validate; the answer names the field.
429
More requests a minute with one token than its plan allows (below). The answer says the limit and when to try again.

Each token counts its reads and its writes per minute, apart from other tokens. How many depends on the plan:

PlanPer token
Pro
120 reads a minute (tokens only read)
Team
300 reads and 60 writes a minute
Agency, Enterprise
600 reads and 120 writes a minute

Send an Idempotency-Key header with a POST and a retry returns the first answer instead of doing it twice. Details in the reference.

NoteReporting deploys from CI can also use its own token and webhook. See Deploy markers.

Still stuck? Write to us.