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.

Base URL

https://app.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) accept an optional severity field with value critical, warning, or info.

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": "abc123def456",
    "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": "GET /pets", "operationKey": "GET /pets" }
  ],
  "skipped": [
    { "operationKey": "GET /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.

Delete Spec

DELETE /api/specs/:id

Fails if any checks still reference the spec via an openapi_conformance assertion.

Sync URL-mode Spec

POST /api/specs/:id/sync

Forces Yorker to re-fetch a url-mode spec immediately. Runners invalidate their cached copy on the next poll.

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 — 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": "GET /pets", "operationKey": "GET /pets" }
  ],
  "skipped": [
    { "operationKey": "GET /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>" }).

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