Time to move to the StatusGator v3 API: What v2 users need to know

We launched the StatusGator v3 REST API back in October,
and it has only gotten better since. v3 is a ground-up redesign built around
organization-level API tokens, a consistent response format, opaque string IDs,
pagination, and a large set of write endpoints for managing monitors, incidents,
and subscribers. We have kept shipping new capabilities for it, and we will keep
doing so.

v2, on the other hand, is done. It still works today, but it receives no new
features and none of the resources we add to v3. Now we are setting a date to
turn it off. If you currently build on the v2 API, this post explains what is
changing, when it is changing, and exactly what you need to do to move over.

We have tried to keep the upgrade path short. For most integrations the work
amounts to swapping your authentication, remapping a handful of field names, and
reading responses from a new envelope.

We are also giving you a clear runway. v2 will keep working for 90 days after
this announcement, with a few scheduled brownouts along the way so you can catch
any lingering dependencies before the final shutoff.

Why v3 is where the work happens

v2 served us well, but it grew up around a single concept: the dashboard. Each
dashboard carried its own credential, responses came back in a few different
shapes depending on the endpoint, and the API was read-only. As customers asked
to automate more of their workflow, those limits became real friction.

v3 fixes the foundation, and it is the version we actively develop:

• One organization token instead of a credential per dashboard.
• A single, predictable response envelope for both success and error cases.
• Full read and write access, so you can create and manage monitors, incidents,
  subscribers, and more directly from the API.
• Pagination, so large accounts get fast, reliable responses.

Interactive, always-current reference docs live at https://statusgator.com/api/v3/docs, served through our OpenAPI UI. This post explains the conceptual changes. Use the reference docs for exhaustive field-by-field schemas.

Migration timeline

Here is the schedule. All times are UTC. We will email organization admins
before each brownout and post reminders on our status page.

Date	Milestone
June 9, 2026	v2 deprecation announced. v2 and v3 continue to run in parallel.
July 15, 2026	First brownout. v2 returns errors for 2 hours, 14:00 to 16:00 UTC.
August 5, 2026	Second brownout. v2 returns errors for 6 hours, 12:00 to 18:00 UTC.
August 19, 2026	Third brownout. v2 returns errors for 24 hours, 00:00 to 24:00 UTC.
September 1, 2026	v2 is retired permanently. All v2 endpoints return 410 Gone.

About the brownouts

A brownout is a planned, temporary outage of the v2 API. During each window, v2
requests fail as if the API were already gone. The brownouts get longer as we
approach the final date so you can confirm your integration no longer depends on
v2 well before it is switched off for good.

If a brownout breaks something in your integration, that is the signal that you
still have v2 traffic to migrate. Nothing is deleted during a brownout, and v2
returns to normal service when the window closes.

After September 1, 2026 there is no further grace period. Plan to complete your
migration before the first brownout on July 15 so you have margin to spare.

1. Base URL

	Base URL
v2	https://statusgator.com/api/v2
v3	https://statusgator.com/api/v3

https://statusgator.com/api/v3 and the old /api_docs path now redirect to the
interactive docs.

2. Authentication

This is the change that affects every integration, so start here.

v2 used per-dashboard tokens

In v2, each dashboard had its own public_token, used in the URL path, and a
private_token used for authentication. You authenticated either with a Bearer
header or HTTP Basic auth where the password was the private token:

# v2, Bearer
curl https://statusgator.com/api/v2/dashboards/PUBLIC_TOKEN \
  -H "Authorization: Bearer PRIVATE_TOKEN"

# v2, HTTP Basic with the private token as the password
curl https://statusgator.com/api/v2/dashboards/PUBLIC_TOKEN \
  -u :PRIVATE_TOKEN

A token only granted access to the single dashboard it belonged to.

v3 uses organization API tokens

v3 uses a single organization-level API token. One token works across all boards
and resources in your organization.

# v3
curl https://statusgator.com/api/v3/boards \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Key points:

• Generate tokens from your StatusGator dashboard using the API menu in the left
  sidebar. Only organization admins can create tokens.
• The Bearer prefix is required.
• HTTP Basic auth is no longer supported. Use the Bearer header only.
• Tokens have a permission level. Full access allows all operations: GET, POST,
  PATCH, and DELETE. Read-only allows GET only. Any write attempt with a
  read-only token returns 403 Forbidden with
  {"success": false, "errors": ["Write operations are not allowed with a read-only token"]}.
• Tokens can be revoked or given an expiration. Inactive tokens return
  401 Unauthorized.

Migration action: Generate a v3 API token from the API menu and replace your
stored dashboard private_tokens with it. Because one token spans the whole
organization, you no longer manage a separate credential per dashboard.

3. Terminology: “Dashboard” becomes “Board”

What v2 called a dashboard is called a board in v3. A board is a collection of
monitors, the services you depend on, belonging to your organization.

Finding the new board ID

v2 addressed dashboards by their public_token in the URL. v3 addresses boards
by an opaque id, a Sqids string such as m2z5x3nOJa. The board’s old
public_token is still returned, so you can map old to new:

curl https://statusgator.com/api/v3/boards \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "m2z5x3nOJa",
      "name": "Cloud Services",
      "public_token": "abc123def456",
      "created_at": "2025-09-12T12:35:54Z",
      "updated_at": "2025-09-12T12:40:54Z"
    }
  ],
  "pagination": { ... }
}

The id field is what you use in v3 URLs, and public_token is your old v2
dashboard token. Match each board to your old dashboard by public_token, then
store the new id for subsequent calls.

4. Response shape: the success and data envelope

v2 returned bare JSON. The dashboard endpoint returned an array of services
directly, and the service endpoint returned a bare object.

v3 wraps every response in a consistent envelope:

// Success
{ "success": true, "data": { ... } }   // or "data": [ ... ]

// Error
{ "success": false, "errors": ["Record not found"] }

List endpoints additionally include pagination metadata. See section 7.

Migration action: Update your client to read the payload from the data key
instead of treating the top-level response as the result, and check the success
boolean and errors array for failures.

5. IDs are now opaque strings

In v2, monitor and service IDs were integers such as 12345. In v3 they are
opaque Sqids strings such as uVLl2YK1rn or m2z5x3nOJa. This applies to
boards, monitors, services, groups, incidents, and the monitor_id used to
filter board history.

Migration action: Treat all IDs as opaque strings. Do not parse them as integers
or assume any ordering.

6. Endpoint mapping

v2 endpoint	v3 equivalent	Notes
GET /dashboards/:dashboard_id, full dashboard with services	GET /boards/:board_id/monitors	The list of services on the board is now the board’s monitors. See field mapping in section 8.
GET /dashboards/:dashboard_id/meta, board name and status	GET /boards/:id	Board metadata: name, tokens, timestamps.
GET /dashboards/:dashboard_id/services/:id, single service with components	GET /boards/:board_id/monitors then GET /boards/:board_id/monitors/:monitor_id/components	Per-monitor components moved to their own endpoint. The global service catalog is at GET /services, GET /services/search, and GET /services/:service_id/components.
GET /dashboards/:dashboard_id/incidents?start_date=&end_date=, historical events	GET /boards/:board_id/history?start_date=&end_date=	Same underlying historical data. See section 9. Do not confuse this with the new /boards/:board_id/incidents resource, which is for user-reported incidents.
GET /dashboards/:dashboard_id/maintenance_events	No direct equivalent	Maintenance now surfaces as a monitor filtered_status of maintenance and within board history events. If you relied on the dedicated maintenance feed, review the board history and monitor status instead.

New in v3 with no v2 equivalent

v3 is fully read and write. Highlights:

• Monitors. Create, update, delete, and pause website_monitors,
  ping_monitors, custom_monitors, and service_monitors under a board.
• Monitor groups. GET/POST/PATCH/DELETE /boards/:board_id/monitor_groups.
• Incidents and updates. GET/POST /boards/:board_id/incidents and
  POST /boards/:board_id/incidents/:incident_id/incident_updates.
• Status page subscribers. List, create, and delete under a board.
• Outage reports. POST /boards/:board_id/outage_reports.
• Services catalog. GET /services, GET /services/search, and
  GET /services/:service_id/components.
• Users. GET /users.
• Monitoring regions. GET /monitoring_regions.
• Ping. GET /ping for an auth and health check.

Some endpoints require add-ons. GET /services, the full catalog firehose,
requires firehose access and returns 403 Forbidden otherwise.

7. Pagination

v2 returned full collections in a single response. v3 list endpoints such as
GET /boards and GET /services are paginated with a page query parameter
that defaults to 1, and include pagination metadata alongside data:

curl "https://statusgator.com/api/v3/boards?page=2" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Migration action: Loop over pages until you have consumed all results instead of
expecting the whole collection in one call.

8. Field mapping: dashboard service to board monitor

A v2 dashboard row, a service, maps to a v3 monitor as follows:

v2 field	v3 field	Notes
id, integer	id, string	Now an opaque Sqids ID.
name	display_name	The monitor’s display name.
status	filtered_status	Status after component filtering.
unfiltered_status	unfiltered_status	Unchanged.
message	last_message	Not scrubbed when up. See below.
details	last_details	Not scrubbed when up. See below.
favicon_url	icon_url	Renamed.
checked_at	checked_at	Unchanged.
paused_at	paused_at	Unchanged.
filter_count	filter_count	Unchanged.
slug, home_page_url, public_url, description	nested under service	For monitor_type: "ServiceMonitor", service details such as slug, home_page_url, status_page_url, landing_page_url, official, and rating live in the service object.
none	monitor_type	New. One of ServiceMonitor, WebsiteMonitor, PingMonitor, CustomMonitor.
none	created_at, updated_at	New timestamps.
none	overridden_status, overridden_message, overrides_locked_at	New. Manual status overrides.
none	early_warning_signal	New. Boolean for detected, unacknowledged outages.
none	position	New. Manual sort order.
none	group	New. The monitor group, if any.

Behavior change: v2 blanked out message and details whenever a service’s
status was up. v3 returns last_message and last_details regardless of
current status. If you relied on the v2 scrubbing behavior, apply that logic
client-side. For example, ignore last_message when filtered_status == "up".

Filtering monitors by status

GET /boards/:board_id/monitors accepts a status filter. Use affected to get
everything that is not up, or pass specific statuses: up, down, warn, or
maintenance.

9. Historical events: incidents becomes board history

The v2 incidents endpoint returned historical status events for a dashboard
over a date range. In v3 this is the board history endpoint, backed by the same
data:

curl "https://statusgator.com/api/v3/boards/BOARD_ID/history?start_date=2025-09-01&end_date=2025-10-01" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Differences:

• Dates are optional. If omitted, start_date defaults to 30 days ago and
  end_date defaults to tomorrow, so today is included. In v2, both start_date
  and end_date were required, and missing them returned 422.
• Filtering by a single monitor uses monitor_id, the new opaque ID. This is the
  same as v2’s monitor_id param but with the new ID format.
• Field renames in each event: v2 v3 start_time started_at end_time ended_at numeric monitor id monitor_id, opaque string favicon_filename icon_url, full URL signal early_warning_signal The name, status, duration, message, and details fields are
  unchanged.

Important: v3 also has a separate /boards/:board_id/incidents resource. That is
not the replacement for v2 incidents. It manages user-reported incidents you
create and post updates to. For the historical event feed you used in v2, use
/boards/:board_id/history.

10. Errors and status codes

v3 returns a consistent error envelope, {"success": false, "errors": [...]},
with these status codes:

Status	Meaning
400 Bad Request	Invalid or missing parameters, such as a bad date or malformed body.
401 Unauthorized	Missing, invalid, expired, or revoked token, or an inactive org.
403 Forbidden	Write attempted with a read-only token, or a feature is not enabled, such as firehose.
404 Not Found	Record not found.
422 Unprocessable Content	Validation failed, such as an invalid date range or invalid record.
500 Internal Server Error	Unexpected server error.

v2 used a mix of {"error": "..."} and {"errors": "..."} shapes. Standardize
on reading the errors array in v3.

11. Rate limiting

Both v2 and v3 are rate limited. Build in retry and backoff handling and respect
429 Too Many Requests responses.

Migration checklist

• Generate an organization API token from the API menu. Admins only.
• Switch auth to Authorization: Bearer <token> and drop HTTP Basic auth.
• Call GET /api/v3/boards and map each old dashboard public_token to its
  new board id.
• Update all URLs to /api/v3/... and use opaque string IDs.
• Read results from the data key and check success and errors.
• Replace GET /dashboards/:id with GET /boards/:board_id/monitors and
  update field names: status to filtered_status, message to
  last_message, favicon_url to icon_url, name to display_name, and
  service fields nested under service.
• Replace GET /dashboards/:id/incidents with
  GET /boards/:board_id/history and update field names such as start_time
  to started_at and end_time to ended_at.
• Handle pagination on list endpoints.
• If you used the v2 maintenance_events feed, switch to monitor status and
  board history.
• Apply the old behavior of blanking message and details when up on the
  client side if you depended on it.
• Review the interactive docs at https://statusgator.com/api/v3/docs for
  the complete schema of any endpoint.

Questions

If you hit a snag during migration, reach out to support before the July 15
brownout so we can help while there is still room in the schedule. We would
rather hear from you early than have a brownout be your first surprise.