API Contract

The Wakeplane HTTP JSON API is versioned under /v1/.

Error envelope

All errors return a JSON body:

{
  "code": "string",
  "error": "human-readable message",
  "details": []
}

HTTP	Code	When
400	`bad_request`	Malformed JSON, invalid query params, missing required fields
400	`validation_failed`	Schedule or patch fails domain validation. `details` populated.
404	`not_found`	Resource does not exist
409	`conflict`	Unique constraint violation (e.g., duplicate schedule name)
500	`internal_error`	Unexpected server error

Pagination

List endpoints use cursor-based pagination.

Request parameters:

Parameter	Default	Description
`limit`	`50`	Max results, 1–200
`cursor`	—	Opaque cursor from previous response

Response:

{
  "items": [...],
  "next_cursor": "opaque-string-or-null"
}

next_cursor is null when there are no more results.

Cursors are valid for the lifetime of the dataset. They are not guaranteed to be stable across schema migrations.

Endpoints

Schedules

GET    /v1/schedules
POST   /v1/schedules
GET    /v1/schedules/{id}
PATCH  /v1/schedules/{id}
DELETE /v1/schedules/{id}

POST   /v1/schedules/{id}/pause
POST   /v1/schedules/{id}/resume
POST   /v1/schedules/{id}/trigger

Runs

GET    /v1/runs
GET    /v1/runs/{id}
GET    /v1/schedules/{id}/runs

POST   /v1/runs/{id}/cancel

Observability

GET    /health      Liveness check
GET    /ready       Readiness check (database + loops initialized)
GET    /v1/status   Scheduler tick timing + run state counts
GET    /metrics     Prometheus text format

Status response

GET /v1/status returns scheduler tick timing plus run state counts:

{
  "tick_at": "2026-03-25T09:00:00Z",
  "due_runs": 0,
  "running": 1,
  "failed": 0,
  "retrying": 0,
  "dead_letter": 0,
  "expired_claims": 0
}