The operational contract for ingest events: auth headers, endpoint shapes, idempotency, limits, and response expectations.

Base URL

Use the public app origin:

https://luota.dev

Do not use api.luota.dev.

Auth header

Every ingest request uses the scoped token in X-Luota-Key.

X-Luota-Key: <monitor-or-workspace-token>

Tokens are scoped. A token for one monitor should not work against another monitor.

Heartbeat ping

POST /v1/monitors/:monitorId/ping

Use this for heartbeat and freshness monitors.

Optional body:

{
  "occurredAt": "2026-05-25T12:00:00.000Z",
  "payload": {
    "source": "cron",
    "deploySha": "abc123"
  }
}

Success returns 202.

Run lifecycle

Start the run:

POST /v1/runs/start

Minimum body:

{
  "monitorId": "22222222-2222-4222-8222-222222222222",
  "externalRunId": "nightly-backup-2026-05-25"
}

Close the run:

POST /v1/runs/:runId/success
POST /v1/runs/:runId/fail

Use the returned run.id from /v1/runs/start. Re-sending the same externalRunId is idempotent and returns the existing run rather than creating duplicate evidence.

Limits

Limit	Value
Raw request body	64 KiB
`payload` JSON	32 KiB
`output` text	32 KiB
Tags	16 key/value pairs
Monitor-token burst	60 requests/minute
Monitor-token sustained	1,000 requests/hour

Large logs belong in object storage. Send a short URL, digest, or summary in payload.

Retry behavior

For network failures, retry the same event with backoff. For run starts, keep the same externalRunId.

For 429, respect Retry-After.

For 409, another completion path already won. Show that conflict in job logs instead of hiding it.

Request ids

Every API response includes X-Request-Id. Log it with the HTTP status and sanitized response body. It lets support find the server-side request without seeing secrets.

API reference