IronWatchDocs
Dashboard
synced 2026-05-29·/api/v1 routes@live
FlipSign · API reference

API reference

Everything you need to drive a status page from code — read pages, manage components, run incidents through their lifecycle, and schedule maintenance. New to FlipSign? Start with the quickstart.

Base URL & authentication

The base URL is https://flipsign.live and all endpoints live under /api/v1. Every request carries a Bearer token (fs_sk_…) created in Settings → API Keys. A missing, placeholder, invalid, or revoked key returns 401 with a descriptive message.

Pages

Status pages are read-only over the API — create, rename, and delete them in the dashboard. Use these to discover a page's id, which every other call needs.

GET/api/v1/pages
BearerPro+ tier

List every status page owned by the API key's user, newest first.

Responses
200OK
Body is { pages: [...] }. Each page carries id, slug, name, description, brandColor, customDomain, isPublic, and createdAt.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
Request
GET /api/v1/pages
curl -X GET "https://flipsign.live/api/v1/pages" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"pages": [
{8 fields}
]
}
GET/api/v1/pages/{id}
BearerPro+ tier

Fetch a single status page you own.

Path parameters
id
string·REQUIRED
The status page UUID.
Responses
200OK
Body is the page object.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No page with that id belongs to you.
Request
GET /api/v1/pages/{id}
curl -X GET "https://flipsign.live/api/v1/pages/:id" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"slug": "acme",
"name": "Acme Status",
"description": "Live status for the Acme platform.",
"brandColor": "#8b5cf6",
"customDomain": "status.acme.com",
"isPublic": true,
"createdAt": "2026-05-20T09:00:00.000Z"
}

Components

Components are the rows on your board. Their valid statuses are operational, degraded, partial_outage, major_outage, and maintenance. Every status change is recorded in the component's history, which powers the uptime heatmap. The number of components per page is capped by your tier.

GET/api/v1/pages/{id}/components
BearerPro+ tier

List a page's components, ordered by position.

Path parameters
id
string·REQUIRED
The status page UUID.
Responses
200OK
Body is { components: [...] } ordered by position.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No page with that id belongs to you.
Request
GET /api/v1/pages/{id}/components
curl -X GET "https://flipsign.live/api/v1/pages/:id/components" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"components": [
{9 fields}
]
}
POST/api/v1/pages/{id}/components
BearerPro+ tier

Create a component on a page. The create is gated atomically against your tier's per-page component limit.

Path parameters
id
string·REQUIRED
The status page UUID.
Request body
name
string·REQUIRED
Display name of the component (e.g. "API"). Trimmed; must be non-empty.
description
string | null·OPTIONAL
Optional longer description shown on the board.
status
string·OPTIONAL
Initial status.
default·"operational"
"operational""degraded""partial_outage""major_outage""maintenance"
position
integer·OPTIONAL
Sort order on the board (non-negative). Defaults to the current component count, appending it last.
Responses
201Created
Component created. Body is the full component row.
400Bad Request
Invalid JSON, missing name, an unknown status, or a negative position.
error.codename is requiredstatus must be one of: …position must be a non-negative integer
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
403Forbidden
Component limit for your tier reached. Upgrade or remove a component first.
error.codeComponent limit reached on this tier (N). …
404Not Found
No page with that id belongs to you.
Request
POST /api/v1/pages/{id}/components
curl -X POST "https://flipsign.live/api/v1/pages/:id/components" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d {
       "name": "API",
       "description": "Public REST API",
       "status": "operational"
     }'
Response201Created
application/json
{
"id": "b4c5d6e7-1234-4abc-9def-0123456789ab",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"groupId": null,
"name": "API",
"description": "Public REST API",
"position": 0,
"status": "operational",
"createdAt": "2026-05-29T15:32:00.000Z",
"updatedAt": "2026-05-29T15:32:00.000Z"
}
GET/api/v1/components/{id}
BearerPro+ tier

Fetch a single component you own (ownership is verified through its page).

Path parameters
id
string·REQUIRED
The component UUID.
Responses
200OK
Body is the component row.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No component with that id belongs to a page you own.
Request
GET /api/v1/components/{id}
curl -X GET "https://flipsign.live/api/v1/components/:id" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"id": "b4c5d6e7-1234-4abc-9def-0123456789ab",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"groupId": null,
"name": "API",
"description": "Public REST API",
"position": 0,
"status": "operational",
"createdAt": "2026-05-29T15:32:00.000Z",
"updatedAt": "2026-05-29T15:32:00.000Z"
}
PATCH/api/v1/components/{id}
BearerPro+ tier

Update a component's name, description, status, or position. This is the deploy-script endpoint: flip a component to major_outage and back.

Path parameters
id
string·REQUIRED
The component UUID.
Request body
name
string·OPTIONAL
New name. Trimmed; rejected if empty.
description
string | null·OPTIONAL
New description, or null to clear it.
status
string·OPTIONAL
New status. The change is recorded in the component's status history, which powers the uptime heatmap.
"operational""degraded""partial_outage""major_outage""maintenance"
position
integer·OPTIONAL
New sort order (non-negative integer).
Responses
200OK
Component updated. Body is the updated row. A no-op body (no recognised fields) returns the unchanged component.
400Bad Request
Invalid JSON, empty name, an unknown status, or a bad position.
error.codename cannot be emptystatus must be one of: …description must be a string or null
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No component with that id belongs to a page you own.
Request
PATCH /api/v1/components/{id}
curl -X PATCH "https://flipsign.live/api/v1/components/:id" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d {
       "status": "major_outage"
     }'
Response200OK
application/json
{
"id": "b4c5d6e7-1234-4abc-9def-0123456789ab",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"groupId": null,
"name": "API",
"description": "Public REST API",
"position": 0,
"status": "major_outage",
"createdAt": "2026-05-29T15:32:00.000Z",
"updatedAt": "2026-05-29T15:32:00.000Z"
}

Incidents

An incident moves through investigating → identified → monitoring → resolved with a severity of minor, major, or critical. Creating an incident, posting an update, or changing its status fans out to email subscribers and alert channels in the background. Resolving (via PATCH status=resolved or a final update) stamps resolvedAt and sends the all-clear once.

GET/api/v1/pages/{id}/incidents
BearerPro+ tier

List a page's incidents, newest first.

Path parameters
id
string·REQUIRED
The status page UUID.
Responses
200OK
Body is { incidents: [...] } ordered by startedAt descending.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No page with that id belongs to you.
Request
GET /api/v1/pages/{id}/incidents
curl -X GET "https://flipsign.live/api/v1/pages/:id/incidents" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"incidents": [
{9 fields}
]
}
POST/api/v1/pages/{id}/incidents
BearerPro+ tier

Open a new incident. An optional message becomes the first update. Subscribers and channels are notified in the background.

Path parameters
id
string·REQUIRED
The status page UUID.
Request body
title
string·REQUIRED
Incident title. Trimmed; must be non-empty.
severity
string·OPTIONAL
Incident severity.
default·"minor"
"minor""major""critical"
status
string·OPTIONAL
Starting lifecycle status.
default·"investigating"
"investigating""identified""monitoring""resolved"
message
string·OPTIONAL
Optional opening message. When present it is stored as the first incident update.
Responses
201Created
Incident created. Subscribers and alert channels are notified in the background. Body is the incident row.
400Bad Request
Invalid JSON, missing title, or an unknown severity/status.
error.codetitle is requiredseverity must be one of: …status must be one of: …
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No page with that id belongs to you.
Request
POST /api/v1/pages/{id}/incidents
curl -X POST "https://flipsign.live/api/v1/pages/:id/incidents" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d {
       "title": "Elevated API error rates",
       "severity": "major",
       "status": "investigating",
       "message": "We are investigating elevated 5xx responses."
     }'
Response201Created
application/json
{
"id": "a3f2c1e0-9b8d-4e21-8c0f-2d1e3f4a5b6c",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"title": "Elevated API error rates",
"severity": "major",
"status": "investigating",
"startedAt": "2026-05-29T17:55:00.000Z",
"resolvedAt": null,
"createdAt": "2026-05-29T17:55:00.000Z",
"updatedAt": "2026-05-29T17:55:00.000Z"
}
GET/api/v1/incidents/{id}
BearerPro+ tier

Fetch a single incident you own (ownership verified through its page).

Path parameters
id
string·REQUIRED
The incident UUID.
Responses
200OK
Body is the incident row.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No incident with that id belongs to a page you own.
Request
GET /api/v1/incidents/{id}
curl -X GET "https://flipsign.live/api/v1/incidents/:id" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"id": "a3f2c1e0-9b8d-4e21-8c0f-2d1e3f4a5b6c",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"title": "Elevated API error rates",
"severity": "major",
"status": "investigating",
"startedAt": "2026-05-29T17:55:00.000Z",
"resolvedAt": null,
"createdAt": "2026-05-29T17:55:00.000Z",
"updatedAt": "2026-05-29T17:55:00.000Z"
}
PATCH/api/v1/incidents/{id}
BearerPro+ tier

Update an incident's title, severity, or status. Setting status=resolved stamps resolvedAt and sends the all-clear; an optional message is recorded as an update.

Path parameters
id
string·REQUIRED
The incident UUID.
Request body
title
string·OPTIONAL
New title. Trimmed; rejected if empty.
severity
string·OPTIONAL
New severity.
"minor""major""critical"
status
string·OPTIONAL
New lifecycle status. Setting resolved stamps resolvedAt and fires the all-clear once.
"investigating""identified""monitoring""resolved"
message
string·OPTIONAL
Optional update body recorded alongside this change.
Responses
200OK
Incident updated. Setting status to resolved sends the all-clear; any other change re-notifies. A no-op body returns the unchanged incident.
400Bad Request
Invalid JSON, empty title, or an unknown severity/status.
error.codetitle cannot be emptyseverity must be one of: …status must be one of: …
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No incident with that id belongs to a page you own.
Request
PATCH /api/v1/incidents/{id}
curl -X PATCH "https://flipsign.live/api/v1/incidents/:id" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d {
       "status": "resolved",
       "message": "The rollback is complete; error rates are back to normal."
     }'
Response200OK
application/json
{
"id": "a3f2c1e0-9b8d-4e21-8c0f-2d1e3f4a5b6c",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"title": "Elevated API error rates",
"severity": "major",
"status": "resolved",
"startedAt": "2026-05-29T17:55:00.000Z",
"resolvedAt": "2026-05-29T18:20:00.000Z",
"createdAt": "2026-05-29T17:55:00.000Z",
"updatedAt": "2026-05-29T18:20:00.000Z"
}
GET/api/v1/incidents/{id}/updates
BearerPro+ tier

List an incident's update entries, oldest first — the public timeline.

Path parameters
id
string·REQUIRED
The incident UUID.
Responses
200OK
Body is { updates: [...] } ordered by createdAt ascending.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No incident with that id belongs to a page you own.
Request
GET /api/v1/incidents/{id}/updates
curl -X GET "https://flipsign.live/api/v1/incidents/:id/updates" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"updates": [
{5 fields}
]
}
POST/api/v1/incidents/{id}/updates
BearerPro+ tier

Append an update to an incident. A new status transitions the incident (resolved stamps resolvedAt). Subscribers and channels are re-notified.

Path parameters
id
string·REQUIRED
The incident UUID.
Request body
body
string·REQUIRED
The update narrative. Trimmed; must be non-empty.
status
string·OPTIONAL
If supplied and different from the incident's current status, transitions the incident. Defaults to the incident's current status.
"investigating""identified""monitoring""resolved"
Responses
201Created
Update appended. Body is { update, incident }. If the status changed, the incident reflects the new status (and resolvedAt when resolved). Notifies subscribers and channels.
400Bad Request
Invalid JSON, missing body, or an unknown status.
error.codebody is requiredstatus must be one of: …
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
No incident with that id belongs to a page you own.
Request
POST /api/v1/incidents/{id}/updates
curl -X POST "https://flipsign.live/api/v1/incidents/:id/updates" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d {
       "body": "Root cause identified — rolling back the bad deploy.",
       "status": "identified"
     }'
Response201Created
application/json
{
"update": {
"id": "c5d6e7f8-2345-4bcd-8ef0-123456789abc",
"incidentId": "a3f2c1e0-9b8d-4e21-8c0f-2d1e3f4a5b6c",
"body": "Root cause identified — rolling back the bad deploy.",
"status": "identified",
"createdAt": "2026-05-29T18:05:00.000Z"
},
"incident": {
"id": "a3f2c1e0-9b8d-4e21-8c0f-2d1e3f4a5b6c",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"title": "Elevated API error rates",
"severity": "major",
"status": "identified",
"resolvedAt": null
}
}

Scheduled maintenance

Planned downtime communicated ahead of time. A window needs a title, an ISO 8601 startsAt, and an ISO 8601 endsAt (strictly after startsAt). The board shows an "Upcoming maintenance" callout before the window and a banner during it. Note the page id must be a UUID — a non-UUID returns 404.

GET/api/v1/pages/{id}/scheduled-maintenance
BearerPro+ tier

List a page's maintenance windows, by start time descending.

Path parameters
id
string·REQUIRED
The status page UUID.
Responses
200OK
Body is { windows: [...] }.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
id is not a UUID, or no page with that id belongs to you.
Request
GET /api/v1/pages/{id}/scheduled-maintenance
curl -X GET "https://flipsign.live/api/v1/pages/:id/scheduled-maintenance" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"windows": [
{8 fields}
]
}
POST/api/v1/pages/{id}/scheduled-maintenance
BearerPro+ tier

Create a maintenance window. Optionally scope it to specific components on the page.

Path parameters
id
string·REQUIRED
The status page UUID.
Request body
title
string·REQUIRED
Maintenance window title. Trimmed and capped at 200 characters.
startsAt
string·REQUIRED
Window start as a strict ISO 8601 timestamp (e.g. 2026-06-01T02:00:00Z).
endsAt
string·REQUIRED
Window end as ISO 8601. Must be strictly after startsAt.
description
string | null·OPTIONAL
Optional details shown on the board.
affectedComponentIds
string[] | null·OPTIONAL
Optional list of component UUIDs to highlight. Every id must belong to this page.
Responses
201Created
Maintenance window created. Body is the window row.
400Bad Request
Invalid JSON, missing title/startsAt/endsAt, malformed ISO 8601, endsAt not after startsAt, or a component id that isn't on this page.
error.codetitle is requiredstartsAt and endsAt are required (ISO 8601)startsAt and endsAt must be valid ISO 8601 timestampsendsAt must be after startsAtOne or more affectedComponentIds don't belong to this page
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
The page id is not a UUID, or no page with that id belongs to you.
Request
POST /api/v1/pages/{id}/scheduled-maintenance
curl -X POST "https://flipsign.live/api/v1/pages/:id/scheduled-maintenance" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d {
       "title": "Database upgrade",
       "description": "Brief read-only window while we upgrade Postgres.",
       "startsAt": "2026-06-01T02:00:00Z",
       "endsAt": "2026-06-01T03:00:00Z"
     }'
Response201Created
application/json
{
"id": "e7f8a9b0-3456-4cde-9f01-23456789abcd",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"title": "Database upgrade",
"description": "Brief read-only window while we upgrade Postgres.",
"startsAt": "2026-06-01T02:00:00.000Z",
"endsAt": "2026-06-01T03:00:00.000Z",
"affectedComponentIds": null,
"createdAt": "2026-05-29T15:32:00.000Z"
}
GET/api/v1/pages/{id}/scheduled-maintenance/{mid}
BearerPro+ tier

Fetch a single maintenance window on a page you own.

Path parameters
id
string·REQUIRED
The status page UUID.
mid
string·REQUIRED
The maintenance window UUID.
Responses
200OK
Body is the maintenance window row.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
Either id is not a UUID, or no matching window belongs to you.
Request
GET /api/v1/pages/{id}/scheduled-maintenance/{mid}
curl -X GET "https://flipsign.live/api/v1/pages/:id/scheduled-maintenance/:mid" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"id": "e7f8a9b0-3456-4cde-9f01-23456789abcd",
"pageId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"title": "Database upgrade",
"description": "Brief read-only window while we upgrade Postgres.",
"startsAt": "2026-06-01T02:00:00.000Z",
"endsAt": "2026-06-01T03:00:00.000Z",
"affectedComponentIds": null,
"createdAt": "2026-05-29T15:32:00.000Z"
}
DELETE/api/v1/pages/{id}/scheduled-maintenance/{mid}
BearerPro+ tier

Delete a maintenance window.

Path parameters
id
string·REQUIRED
The status page UUID.
mid
string·REQUIRED
The maintenance window UUID.
Responses
200OK
Body is { deleted: true }.
401Unauthorized
Missing, placeholder, invalid, or revoked API key.
404Not Found
Either id is not a UUID, or no matching window belongs to you.
Request
DELETE /api/v1/pages/{id}/scheduled-maintenance/{mid}
curl -X DELETE "https://flipsign.live/api/v1/pages/:id/scheduled-maintenance/:mid" \
  -H "Authorization: Bearer <FLIPSIGN_API_KEY>" \
Response200OK
application/json
{
"deleted": true
}

Errors

Every error returns JSON with an error field describing what went wrong.

StatusMeaning
400Invalid JSON, missing required field, bad enum value, or a malformed timestamp
401Missing, placeholder, invalid, or revoked API key
403Component limit for your tier reached
404Page, component, incident, or maintenance window not found (or not yours)

Tiers & limits

TierPagesComponents/pageSubscribers/pageAPI
Free1550—
Starter115500—
Pro550unlimitedyes
Businessunlimited100unlimitedyes

Custom domains are Starter+; the embeddable widget and the /api/v1 surface are Pro+. Custom CSS and the audit log are Business.

tip See the live numbers and upgrade on the pricing page.