Skip to main content

REST API

Everything the console shows and does is available over a REST API, so a deployment pipeline can open a maintenance window, a script can acknowledge an incident, and a dashboard of yours can read the same series the console draws.

  • Base URL: https://api.wakora.io/v1/
  • Auth: Authorization: Bearer <token>
  • Format: JSON in, JSON out. Timestamps in answers are ISO 8601 UTC; from and to parameters accept a unix timestamp, a negative offset in seconds (from=-3600 for the last hour) or a datetime string.
  • Spec: GET /v1/openapi.json returns the machine-readable OpenAPI document with your token, always current with the deployed API.

The API is available on the Pro plan and above; see the pricing page.

Tokens and scopes​

Two kinds of tokens work here:

  • Personal tokens (wka_...), minted in My account, API tokens. A token is bound to exactly one workspace when it is created and lives with your membership: leave the workspace and the token stops working the same minute.
  • AI agent tokens (wkm_...), minted per workspace in Settings, AI agents for the MCP server. They are accepted on REST too; actions they perform show up as "AI" on incident timelines.

Every token carries a scope, and scopes nest: read (telemetry and lists), act (acknowledge, resolve, maintenance windows, heartbeats, Jira issues, test runs), admin (rules, sites, keys, team). A token's scope can never exceed the role of the person who minted it, and the check runs on every request: an admin who is downgraded to viewer keeps their tokens but they now answer as read. A call above the token's scope answers 403 with an explanation.

The token rides the Authorization header (preferred) or a ?key= query parameter. Write parameters ride a JSON body or the query string, either works.

Errors and limits​

Errors are JSON with a matching status code:

{ "error": "this token is scoped read - the call needs act" }
StatusMeaning
400bad or missing parameters. Telemetry reads that could span a whole fleet need server=<uuid>; the error says so.
401unknown, revoked or plan-blocked token.
403the token's scope or the workspace's plan is too low for this call.
404no such resource in this workspace; also for unknown /v1/ paths, with a hint.
409conflict, for example a duplicate name.
429rate limited: about 10 requests per second with a burst of 30 per source, answered with Retry-After.
502the telemetry store did not answer; retry.

Reads of historical data are clamped to the retention of your plan; a window that reaches further back returns what the plan keeps, not an error.

Quick start​

# open incidents
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.wakora.io/v1/incidents?state=open"

# acknowledge incident 42
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "https://api.wakora.io/v1/incidents/42/ack"

# a CPU series of one host over the last hour
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.wakora.io/v1/metrics?server=$UUID&name=host.cpu.used_pct&from=-3600"

Host identifiers are the UUIDs the console shows on a host page (never hostnames, two workspaces can both own a db-1). Incident numbers are the per-workspace numbers the console shows.

Resources​

Every call is written to the workspace audit log with the token that made it.