REST API

The Yorker REST API provides programmatic access to monitors, alerts, SLOs, notification channels, and locations. All endpoints return JSON and validate request bodies through shared Zod schemas.

Authentication

To authenticate API requests, include your API key in the Authorization header as a Bearer token.

Authorization: Bearer sk_...

All endpoints require authentication. Unauthenticated requests return 401 Unauthorized.

To mint, list, rotate, or revoke keys, see the API Keys reference.

Base URL

https://yorkermonitoring.com

Common Response Patterns

Success

Successful responses return a 2xx status code with a JSON body.

Validation Error (400)

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": { "name": ["String must contain at least 1 character(s)"] },
    "formErrors": []
  }
}

Not Found (404)

{ "error": "Check not found" }

Conflict (409)

{ "error": "Channel is in use by alert rule \"my-alert\". Remove it from those first." }

Checks

List Checks

To list all checks for your team:

GET /api/checks

Response 200

{
  "checks": [
    {
      "id": "chk_abc123",
      "teamId": "team_xyz",
      "name": "Homepage",
      "type": "http",
      "configJson": { "url": "https://example.com", "method": "GET", "timeoutMs": 30000, "followRedirects": true, "maxRedirects": 5, "assertions": [] },
      "frequencySeconds": 300,
      "locations": ["loc_us_east", "loc_eu_central"],
      "enabled": true,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": null
    }
  ]
}

Create Check

To create a new check:

POST /api/checks

Request body -- validated through CreateCheckSchema

For HTTP checks:

httpConfig fields:

For browser checks:

browserConfig fields:

For MCP checks:

mcpConfig fields:

Response 201

{
  "check": {
    "id": "chk_abc123",
    "teamId": "team_xyz",
    "name": "Homepage",
    "type": "http",
    "configJson": { "url": "https://example.com", "method": "GET", "timeoutMs": 30000, "followRedirects": true, "maxRedirects": 5, "assertions": [] },
    "frequencySeconds": 300,
    "locations": ["loc_us_east"],
    "enabled": true,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": null
  }
}

Error 403 -- Plan limit exceeded.

Get Check

To get a single check with its 50 most recent results:

GET /api/checks/:id

Response 200

{
  "check": { "id": "chk_abc123", "name": "Homepage", "..." : "..." },
  "results": [
    {
      "id": "res_xyz789",
      "checkId": "chk_abc123",
      "runId": "run_abc",
      "locationId": "loc_us_east",
      "status": "success",
      "responseTimeMs": 142,
      "httpStatusCode": 200,
      "startedAt": "2025-01-15T10:05:00.000Z",
      "completedAt": "2025-01-15T10:05:00.142Z"
    }
  ]
}

Update Check

To update an existing check:

PUT /api/checks/:id

Request body -- all fields are optional (partial update):

Response 200

{ "check": { "id": "chk_abc123", "..." : "..." } }

Delete Check

To delete a check and its results:

DELETE /api/checks/:id

Response 200

{ "success": true }

List Check Results

To get paginated results for a check:

GET /api/checks/:id/results

Query parameters:

Response 200

{
  "results": [
    {
      "id": "res_xyz789",
      "checkId": "chk_abc123",
      "runId": "run_abc",
      "locationId": "loc_us_east",
      "status": "success",
      "responseTimeMs": 142,
      "httpStatusCode": 200,
      "timing": {
        "dnsLookupMs": 12,
        "tcpConnectMs": 18,
        "tlsHandshakeMs": 25,
        "ttfbMs": 80,
        "contentTransferMs": 7,
        "totalMs": 142
      },
      "startedAt": "2025-01-15T10:05:00.000Z",
      "completedAt": "2025-01-15T10:05:00.142Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

When detail=true, browser check results also include networkRequestsJson, screenshotsJson, and consoleLogsJson fields.

Trigger Ad-Hoc Run

To trigger an immediate check run across all assigned locations:

POST /api/checks/:id/trigger

Request body: none

Response 200

{
  "triggered": true,
  "locations": 3
}

Alerts

List Alert Rules

To list all alert rules for a check:

GET /api/checks/:id/alerts

Response 200

{
  "alerts": [
    {
      "id": "alert_abc123",
      "checkId": "chk_xyz",
      "name": "downtime-alert",
      "enabled": true,
      "conditions": [
        { "type": "consecutive_failures", "count": 3 }
      ],
      "channelIds": ["nch_abc"],
      "channels": [
        { "type": "slack", "webhookUrl": "https://hooks.slack.com/..." }
      ],
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": null
    }
  ]
}

The channels array contains resolved channel configurations for display. The channelIds array contains the raw channel IDs.

Create Alert Rule

To create an alert rule for a check:

POST /api/checks/:id/alerts

Request body -- validated through CreateAlertRuleSchema:

Response 201

{ "id": "alert_abc123" }

Update Alert Rule

To update an existing alert rule:

PUT /api/alerts/:alertId

Request body -- validated through UpdateAlertRuleSchema (all fields optional):

Response 200

{ "success": true }

Delete Alert Rule

To delete an alert rule:

DELETE /api/alerts/:alertId

Response 200

{ "success": true }

Alert Conditions

Each condition in the conditions array must have a type field. Available types:

All SSL conditions (including ssl_expiry), mcp_schema_drift, and baseline_anomaly accept an optional severity field with value critical, warning, or info. mcp_schema_drift and baseline_anomaly default to warning; SSL conditions fall back to critical via the evaluator when unset.

Alert Instances

Alert instances represent individual occurrences of a triggered alert rule. They track state transitions through a lifecycle: active -> acknowledged -> resolved (or recovered automatically).

List Alert Instances

To list alert instances for your team:

GET /api/alerts/instances

Query parameters:

Response 200

{
  "instances": [
    {
      "id": "ainst_abc123",
      "ruleId": "alert_xyz",
      "checkId": "chk_xyz",
      "state": "active",
      "severity": "critical",
      "startedAt": "2025-01-15T10:00:00.000Z",
      "acknowledgedAt": null,
      "recoveredAt": null,
      "resolvedAt": null,
      "durationMs": null,
      "notificationCount": 2,
      "contextJson": {},
      "muted": false,
      "ruleName": "downtime-alert",
      "checkName": "Homepage"
    }
  ],
  "limit": 50,
  "offset": 0
}

Get Alert Instance

To get a single alert instance with its full event timeline:

GET /api/alerts/instances/:id

Response 200

{
  "instance": {
    "id": "ainst_abc123",
    "ruleId": "alert_xyz",
    "checkId": "chk_xyz",
    "teamId": "team_xyz",
    "state": "acknowledged",
    "severity": "critical",
    "triggeringResultId": "res_abc",
    "triggeringTraceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "recoveryResultId": null,
    "startedAt": "2025-01-15T10:00:00.000Z",
    "acknowledgedAt": "2025-01-15T10:05:00.000Z",
    "acknowledgedBy": "user_abc",
    "recoveredAt": null,
    "resolvedAt": null,
    "durationMs": null,
    "notificationCount": 2,
    "contextJson": {},
    "muted": false,
    "ruleName": "downtime-alert",
    "checkName": "Homepage"
  },
  "events": [
    {
      "id": "aevt_abc",
      "instanceId": "ainst_abc123",
      "type": "triggered",
      "actorId": null,
      "createdAt": "2025-01-15T10:00:00.000Z"
    },
    {
      "id": "aevt_def",
      "instanceId": "ainst_abc123",
      "type": "acknowledged",
      "actorId": "user_abc",
      "createdAt": "2025-01-15T10:05:00.000Z"
    }
  ]
}

Acknowledge Alert Instance

To acknowledge an active alert instance (transitions from active to acknowledged):

POST /api/alerts/instances/:id/acknowledge

Request body: none

Response 200

{ "success": true, "state": "acknowledged" }

Error 409 -- Instance is not in active state.

Resolve Alert Instance

To manually resolve an alert instance (transitions from active or acknowledged to resolved):

POST /api/alerts/instances/:id/resolve

Request body: none

Response 200

{ "success": true, "state": "resolved", "durationMs": 300000 }

Error 409 -- Instance is already recovered or resolved.

Notification Channels

List Channels

To list all notification channels for your team:

GET /api/notification-channels

Response 200

{
  "channels": [
    {
      "id": "nch_abc123",
      "name": "ops-slack",
      "type": "slack",
      "config": { "type": "slack", "webhookUrl": "https://hooks.slack.com/..." },
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": null
    }
  ]
}

Create Channel

To create a notification channel:

POST /api/notification-channels

Request body -- validated through CreateNotificationChannelSchema:

channel object (discriminated by type):

Slack:

Email:

Webhook:

Response 201

{
  "channel": {
    "id": "nch_abc123",
    "name": "ops-slack",
    "type": "slack",
    "config": { "type": "slack", "webhookUrl": "https://hooks.slack.com/..." }
  }
}

Error 409 -- A channel with that name already exists.

Get Channel

To get a single notification channel:

GET /api/notification-channels/:id

Response 200

{
  "channel": {
    "id": "nch_abc123",
    "name": "ops-slack",
    "type": "slack",
    "config": { "type": "slack", "webhookUrl": "https://hooks.slack.com/..." },
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": null
  }
}

Update Channel

To update a notification channel:

PUT /api/notification-channels/:id

Request body -- validated through UpdateNotificationChannelSchema (all fields optional):

Response 200

{ "success": true }

Error 400 -- Channel type cannot be changed. Error 409 -- A channel with that name already exists.

Delete Channel

To delete a notification channel:

DELETE /api/notification-channels/:id

The channel must not be referenced by any alert rules or SLOs. Remove references first.

Response 200

{ "success": true }

Error 409 -- Channel is still in use by an alert rule or SLO.

SLOs

List SLOs

To list all SLO definitions for your team:

GET /api/slos

Query parameters:

Response 200

{
  "slos": [
    {
      "id": "slo_abc123",
      "checkId": "chk_xyz",
      "teamId": "team_xyz",
      "name": "Homepage SLO",
      "targetBasisPoints": 9990,
      "windowDays": 30,
      "burnRateAlertsEnabled": true,
      "channelIds": ["nch_abc"],
      "enabled": true,
      "sloType": "check",
      "patternId": null,
      "sliType": "availability",
      "perfThresholdMs": null,
      "scope": "check",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": null,
      "checkName": "Homepage"
    }
  ],
  "limit": 50,
  "offset": 0
}

Create SLO

To create a new SLO definition:

POST /api/slos

Request body -- validated through CreateSloSchema (discriminated union on sloType):

For check-based SLOs:

Response 201

{
  "slo": {
    "id": "slo_abc123",
    "checkId": "chk_xyz",
    "teamId": "team_xyz",
    "name": "Homepage SLO",
    "targetBasisPoints": 9990,
    "windowDays": 30,
    "burnRateAlertsEnabled": true,
    "channelIds": [],
    "enabled": true,
    "sloType": "check",
    "patternId": null,
    "sliType": "availability",
    "perfThresholdMs": null,
    "scope": "check",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": null
  }
}

Get SLO

To get a single SLO definition:

GET /api/slos/:id

Response 200

{
  "slo": {
    "id": "slo_abc123",
    "checkId": "chk_xyz",
    "name": "Homepage SLO",
    "targetBasisPoints": 9990,
    "windowDays": 30,
    "burnRateAlertsEnabled": true,
    "channelIds": ["nch_abc"],
    "enabled": true,
    "sloType": "check",
    "checkName": "Homepage",
    "..." : "..."
  }
}

Update SLO

To update an existing SLO definition:

PUT /api/slos/:id

Request body -- validated through UpdateSloSchema (all fields optional):

Note: sloType, scope, and sliType are immutable after creation. Changing them would invalidate historical data.

Response 200

{
  "slo": { "id": "slo_abc123", "..." : "..." }
}

Delete SLO

To delete an SLO definition:

DELETE /api/slos/:id

Response 200

{ "success": true }

Get SLO Status

To get the current computed state of an SLO (availability, error budget, burn rates):

GET /api/slos/:id/status

Response 200

{
  "state": {
    "sloId": "slo_abc123",
    "checkId": "chk_xyz",
    "patternId": null,
    "name": "Homepage SLO",
    "sloType": "check",
    "sliType": "availability",
    "targetBasisPoints": 9990,
    "windowDays": 30,
    "availability": 0.9995,
    "totalCount": 8640,
    "successCount": 8636,
    "avgDurationMs": null,
    "perfComplianceRatio": null,
    "errorBudgetTotal": 43.2,
    "errorBudgetConsumed": 21.6,
    "errorBudgetRemaining": 21.6,
    "budgetConsumedRatio": 0.5,
    "burnRate1h": 0.0,
    "burnRate6h": 0.2,
    "burnRate24h": 0.5
  }
}

Locations

List Locations

To list all available monitoring locations (hosted and private):

GET /api/locations

Query parameters:

Response 200

{
  "locations": [
    {
      "id": "loc_us_east",
      "name": "us-east",
      "region": "iad",
      "displayName": "US East (Ashburn)",
      "type": "hosted",
      "status": "active",
      "health": "active",
      "latitude": 39.0438,
      "longitude": -77.4874
    },
    {
      "id": "loc_staging_eu",
      "name": "staging-eu",
      "region": "private",
      "displayName": "Staging EU",
      "type": "private",
      "status": "active",
      "health": "active",
      "teamId": "team_xyz",
      "lastHeartbeat": "2025-01-15T10:03:45.000Z"
    }
  ]
}

NL Generation

POST /api/checks/generate has two modes, distinguished by whether the request body includes a spec field:

• Playwright mode: default. Generates a Playwright browser script from a natural language description via Claude. Used by the dashboard's NL monitor builder.
• Spec mode: generates HTTP checks from an OpenAPI document by reusing the same pipeline as POST /api/specs/:id/generate-checks. The spec can be referenced by ID, fetched from a URL, or matched by name against an existing spec.

Generate Playwright Script

To generate a Playwright monitoring script from a natural language description:

POST /api/checks/generate

Request body:

Response 200

{
  "mode": "playwright",
  "script": "// @step: Navigate to homepage\nawait page.goto('https://example.com');\n...",
  "description": "Monitor the login flow",
  "model": "claude-sonnet-4-20250514"
}

Error 503: NL creation not configured (server missing ANTHROPIC_API_KEY).

Generate Checks From OpenAPI Spec

To generate HTTP checks from an OpenAPI spec in a single round trip (useful when an integration knows the spec source but does not want to manage the spec entity separately):

POST /api/checks/generate

Request body:

Spec reference variants: spec.source selects how the spec is resolved:

Response 200 (or 201 if at least one check was created). Same envelope as POST /api/specs/:id/generate-checks. The mode field marks this as the spec branch and spec.newlyCreated indicates whether the URL variant inserted a brand-new spec row.

{
  "mode": "spec",
  "spec": { "id": "spec_abc", "name": "Petstore API", "newlyCreated": true },
  "created": [
    { "id": "chk_xyz", "name": "Petstore API: GET /pets", "operationKey": "GET /pets" }
  ],
  "skipped": [
    {
      "operationKey": "GET /pets/{id}",
      "operationId": "getPetById",
      "method": "GET",
      "pathTemplate": "/pets/{id}",
      "reason": "already_exists"
    }
  ],
  "summary": {
    "operationsInSpec": 12,
    "eligible": 11,
    "created": 10,
    "skipped": 1,
    "labelAttachmentFailures": 0
  }
}

Errors:

• 400: invalid request body ({ error: "Validation failed", details: {...} }).
• 403: plan limit reached. Body contains { error: "<plan limit message>" }.
• 404: spec not found (id and name variants only).
• 409: confirmation required: { error: "This spec would create N new monitors. Confirm to create all of them.", requiresConfirmation: true, operationCount: N, threshold: 50 }. Re-submit with confirm: true.
• 409: (url variant only) a spec with the resolved name already exists with different content. Pass an explicit name or use the id variant.
• 422: the loaded spec content failed to parse, OR the upstream URL fetch returned an error / non-OpenAPI body / exceeded the 10 MB cap. Body contains { error: "<details>" }.

API Specs

API specs store OpenAPI documents that HTTP checks can validate against via the openapi_conformance assertion. See Assertions: openapi_conformance.

List Specs

GET /api/specs

Returns a summary list (no full contents; use the detail endpoint to fetch the parsed spec).

Create Spec

POST /api/specs

Request body, discriminated by sourceType:

Upload mode:

URL mode:

Get Spec

GET /api/specs/:id

Returns the full parsed spec including contentJson.

Update Spec

PUT /api/specs/:id

Accepts name, content (switches to upload mode), or sourceUrl (switches to url mode). You cannot provide both content and sourceUrl in the same request, and a body with none of the three fields returns 400 No fields to update.

Delete Spec

DELETE /api/specs/:id

Returns 204 No Content on success. Generated monitors are not deleted; their openapi_conformance assertion still references the spec ID. The runner's in-memory spec cache is best-effort (5-minute TTL, 50-entry LRU cap, and specs over 2 MB are not cached at all), so the assertion may keep validating against a cached spec for up to 5 minutes after deletion. Specs that were never cached (size > 2 MB) or that have already been LRU-evicted will fail on the very next run, when the runner's getSpec call returns 404. Re-creating a spec with the same ID is not supported (IDs are unique). To clean up after a delete, either generate a new spec and re-point the affected checks' assertions at the new ID, or delete the orphaned checks.

Sync URL-mode Spec

POST /api/specs/:id/sync

Forces Yorker to re-fetch a url-mode spec immediately. Returns 400 when called on an upload-mode spec. The response is the spec summary plus a changed flag indicating whether the new SHA-256 contentHash differs from the stored one (Yorker only writes a new contentJson when the hash actually changes, avoiding write amplification on periodic syncs):

{
  "spec": {
    "id": "spec_abc",
    "teamId": "team_xyz",
    "name": "Petstore API",
    "sourceType": "url",
    "sourceUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "contentHash": "...",
    "version": "1.0.0",
    "lastSyncedAt": "2026-05-15T07:00:00.000Z",
    "createdAt": "2026-05-15T06:00:00.000Z",
    "updatedAt": "2026-05-15T07:00:00.000Z"
  },
  "changed": true
}

When changed: true, runners invalidate their cached copy on the next poll. Generated checks pick up the new schema automatically; you do not need to re-run generate-checks unless the spec added new operations you want to monitor.

Generate Checks From Spec

POST /api/specs/:id/generate-checks

Generates one HTTP check per operation in the spec. Operations that already have a corresponding check are skipped, so re-running this endpoint is idempotent. Returns 201 when at least one check is created, 200 otherwise.

Request body:

Response 201 / 200

{
  "spec": { "id": "spec_abc", "name": "Petstore API" },
  "created": [
    { "id": "chk_xyz", "name": "Petstore API: GET /pets", "operationKey": "GET /pets" }
  ],
  "skipped": [
    {
      "operationKey": "GET /pets/{id}",
      "operationId": "getPetById",
      "method": "GET",
      "pathTemplate": "/pets/{id}",
      "reason": "already_exists"
    }
  ],
  "summary": {
    "operationsInSpec": 12,
    "eligible": 11,
    "created": 10,
    "skipped": 1,
    "labelAttachmentFailures": 0
  }
}

Errors:

• 400: invalid request body ({ error: "Validation failed", details: {...} }).
• 403: plan limit reached. Body contains { error: "<plan limit message>" }.
• 404: spec not found (or belongs to another team).
• 409: confirmation required: { error: "This spec would create N new monitors. Confirm to create all of them.", requiresConfirmation: true, operationCount: N, threshold: 50 }. Re-submit with confirm: true.
• 422: the stored spec content failed to parse ({ error: "<parser message>" }).

Events

The unified events endpoint returns check executions and alert state transitions as a single time-ordered stream. See Events concepts for the model.

List Events

GET /api/events

Query parameters:

Response 200

{
  "events": [
    {
      "id": "res_xyz789",
      "eventType": "check.completed",
      "timestamp": "2026-05-14T10:05:00.142Z",
      "checkId": "chk_abc123",
      "checkName": "Homepage",
      "checkType": "http",
      "severity": null,
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "summary": "142 ms",
      "resourceAttributes": { "synthetics.check.id": "chk_abc123", "...": "..." },
      "attributes": { "synthetics.http.response_time": 142, "synthetics.check.success": 1, "...": "..." }
    }
  ],
  "limit": 50,
  "offset": 0,
  "hasMore": true
}

Deployment Events

Record and query deployment markers, which the dashboard correlates with check-result anomaly windows.

Record a Deployment

POST /api/events/deployments

Request body (validated through CreateDeploymentEventSchema, snake_case for CI-friendliness):

Response 201

{
  "deployment": {
    "id": "dep_abc123",
    "teamId": "team_xyz",
    "service": "checkout-api",
    "version": "v2.18.0",
    "environment": "production",
    "commitSha": "a1b2c3d4",
    "commitMessage": "fix: retry idempotency",
    "deployedBy": "drewpost",
    "source": "github-actions",
    "url": null,
    "deployedAt": "2026-05-14T10:00:00.000Z",
    "createdAt": "2026-05-14T10:00:00.000Z"
  }
}

The response uses camelCase field names matching the rest of the read API. When a team OTLP endpoint is configured, a successful POST also enqueues a synthetics.deployment.created OTLP log event via the outbox; teams without an OTLP endpoint configured get the row in deployment_events only.

List Deployments

GET /api/events/deployments

Query parameters:

Returns up to 50 deployments, ordered by deployedAt DESC.

Response 200

{
  "deployments": [
    {
      "id": "dep_abc123",
      "service": "checkout-api",
      "version": "v2.18.0",
      "environment": "production",
      "commitSha": "a1b2c3d4",
      "commitMessage": "fix: retry idempotency",
      "deployedBy": "drewpost",
      "source": "github-actions",
      "url": null,
      "deployedAt": "2026-05-14T10:00:00.000Z",
      "createdAt": "2026-05-14T10:00:00.000Z"
    }
  ]
}

Maintenance Windows

Maintenance windows silence or pause checks during scheduled work. See Configuration: maintenanceWindows for the YAML schema.

List Maintenance Windows

GET /api/maintenance-windows

Create Maintenance Window

POST /api/maintenance-windows

Request body:

Get / Update / Delete Maintenance Window

GET    /api/maintenance-windows/:id
PUT    /api/maintenance-windows/:id
DELETE /api/maintenance-windows/:id