API Contract

Wakeplane exposes a JSON HTTP API for schedule and run management. The route tables on this page are aligned to internal/api/http.go in the source repo.

Operator warning: Wakeplane currently has no auth or RBAC. Bind it to localhost, a trusted subnet, VPN, Tailscale, or a reverse-proxied private network. Do not expose it directly to the public internet. See Security.

Health And Readiness

Method	Path	Description
GET	/healthz	Liveness probe. Returns {"ok":true}.
GET	/readyz	Readiness probe. Returns {"ok":true,"storage":"ok"} when the store is reachable.

Operational Status And Metrics

Method	Path	Description
GET	/v1/status	Operational status including scheduler timing, worker counts, and run counts.
GET	/v1/metrics	Prometheus text metrics for schedules, runs, leases, and executor outcomes.

Schedule Management

Method	Path	Description
POST	/v1/schedules	Create a schedule. Returns 201 with the full schedule.
GET	/v1/schedules	List schedules. Supports enabled, limit, and cursor.
GET	/v1/schedules/{id}	Get one schedule including computed next_run_at.
PUT	/v1/schedules/{id}	Replace a schedule. All fields required.
PATCH	/v1/schedules/{id}	Patch a schedule. Only provided fields change.
DELETE	/v1/schedules/{id}	Delete a schedule and dependent rows.
POST	/v1/schedules/{id}/pause	Pause a schedule.
POST	/v1/schedules/{id}/resume	Resume a schedule and recompute next_run_at.
POST	/v1/schedules/{id}/trigger	Create a manual run immediately. Requires {"reason":"..."}.
GET	/v1/schedules/{id}/runs	List runs for one schedule. Supports status, limit, and cursor.

Run Inspection

Method	Path	Description
GET	/v1/runs	List runs across all schedules. Supports schedule_id, status, limit, and cursor.
GET	/v1/runs/{id}	Get one run including result fields.
GET	/v1/runs/{id}/receipts	List execution receipts for a run.

Error Envelope

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

HTTP Status	Code	When
400	bad_request	Malformed JSON, invalid query parameters, or invalid trigger reason
400	validation_failed	Schedule create or patch validation failed
404	not_found	Schedule or run ID does not exist
500	internal_error	Unexpected server error

Pagination And Filtering

List endpoints use cursor-based pagination with newest-first ordering.

Parameter	Applies to	Behavior
limit	schedule and run list endpoints	Default 50. Invalid or non-positive values fall back to 50.
cursor	schedule and run list endpoints	Opaque cursor from a previous response. Invalid values return 400 bad_request.
`enabled=true	false`	GET /v1/schedules
schedule_id=<id>	GET /v1/runs	Filter runs to a single schedule.
status=<value>	run list endpoints	Accepted values: cancelled, claimed, dead_lettered, failed, pending, retry_scheduled, running, skipped, succeeded.

Content Types

• Request bodies: application/json
• JSON responses: application/json
• Metrics response: text/plain; version=0.0.4