API Contract

Wakeplane exposes a JSON HTTP API for schedule and run management. The route tables on this page are generated from internal/api/http.go so the published surface stays aligned with the server.

Operator warning: Wakeplane supports single-operator bearer auth for /v1/..., but it has no RBAC or multi-tenancy. 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 active store dialect, scheduler timing, worker counts, run counts, retention, and security posture.
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 query params.
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 its dependent runs, leases, receipts, and dead letters.
POST	/v1/schedules/{id}/pause	Pause a schedule by setting enabled=false and recording paused_at.
POST	/v1/schedules/{id}/resume	Resume a schedule by setting enabled=true, clearing paused_at, and recomputing next_run_at.
POST	/v1/schedules/{id}/trigger	Create a manual run immediately. Requires {"reason":"..."}.
GET	/v1/schedules/{id}/runs	List runs for a specific schedule. Supports status, target_kind, limit, and cursor.

Run inspection

Method	Path	Description
GET	/v1/runs	List runs across all schedules. Supports schedule_id, status, target_kind, limit, and cursor.
GET	/v1/runs/{id}	Get one run including result fields, receipts, attempt history, and dead-letter details when present.
GET	/v1/runs/{id}/receipts	List execution receipts for a run.

Error envelope

All API errors return JSON with this shape:

{
  "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

Go’s default 404 method not allowed and malformed transport-level responses do not use the JSON envelope.

Pagination and filtering

List endpoints use cursor-based pagination with newest-first ordering (created_at DESC, id DESC).

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	Strict boolean filter. Any other value returns 400 bad_request.
schedule_id=<id>	GET /v1/runs	Filter runs to a single schedule.
target_kind=http|shell|workflow	run list endpoints	Filter runs by typed target kind. Any other value returns 400 bad_request.
status=<value>	run list endpoints	Accepted values: cancelled, claimed, dead_lettered, failed, pending, retry_scheduled, running, skipped, succeeded. Invalid values return 400 bad_request.

Run list responses include operator-console fields: schedule_name, target_kind, claimed_by_worker_id, retry_available_at, and error_text when available. GET /v1/runs/{id} returns the full run plus receipts, attempts, and dead_letter when present so the UI and API expose the same execution truth.

Content types

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

Status response shape

{
  "service": "wakeplane",
  "version": "0.2.0-beta.1",
  "started_at": "2026-03-25T12:00:00Z",
  "database": {
    "driver": "sqlite",
    "path": "/var/lib/wakeplane/data.db"
  },
  "scheduler": {
    "loop_interval_seconds": 5,
    "last_tick_at": "2026-03-25T12:00:05Z",
    "due_runs": 0,
    "next_due_schedule_id": "sch_01...",
    "next_due_run_at": "2026-03-25T12:05:00Z"
  },
  "workers": {
    "active": 0,
    "claimed_but_expired": 0
  },
  "runs": {
    "running": 0,
    "failed": 0,
    "retry_queued": 0,
    "dead_letter": 0
  },
  "retention": {
    "run_retention_days": 30,
    "receipt_max_bytes": 262144
  },
  "security": {
    "auth_required": true,
    "request_audit": true
  }
}

Trigger response shape

{
  "run_id": "run_01...",
  "schedule_id": "sch_01...",
  "occurrence_key": "manual:run_01...",
  "status": "pending",
  "created_at": "2026-03-25T12:00:00Z"
}

Default policy values on create

When schedule policy or retry fields are omitted, Wakeplane applies these defaults:

{
  "policy": {
    "overlap": "forbid",
    "misfire": "run_once_if_late",
    "timeout_seconds": 300,
    "max_concurrency": 1
  },
  "retry": {
    "max_attempts": 0,
    "strategy": "exponential",
    "initial_delay_seconds": 30,
    "max_delay_seconds": 900
  }
}