REST API reference

POST/api/auth/login

Exchanges admin credentials for a control-plane JWT. The only public endpoint under /api.

{"username":"admin","password":"…"}

{"token":"eyJhbGciOiJIUzI1NiJ9…","tokenType":"Bearer","expiresInSeconds":3600}

Errors. 401 invalid credentials for a wrong username, a wrong password, and an unconfigured console — the three are indistinguishable on purpose. 429 once this source IP has been throttled.

GET/api/pools/resources

KPI summary plus one row per resource your tenant's pool knows — registered, blocklisted, or merely seen in a cell. Rows are ordered by kind then value.

{
  "summary": {
    "registered": 42,
    "blocklisted": 1,
    "totalCells": 96,
    "cellsByState": {"HEALTHY": 81, "COOLING": 12, "RECOVERING": 3, "BLOCKLISTED": 0}
  },
  "resources": [
    {
      "kind": "PROXY",
      "value": "proxy-1.example.net:8080",
      "registered": true,
      "blocked": false,
      "blockedUntil": null,
      "blockPermanent": false,
      "contexts": 2,
      "state": "COOLING",
      "score": -34.0,
      "recentWindow": [true, true, false, false]
    }
  ]
}

A row aggregates the resource's cells into a representative rollup, and the rule is "surface the weakest context" — that is the one an operator needs to see first:

• state — the worst-severity cell state (BLOCKLISTED > COOLING > RECOVERING > HEALTHY), or BLOCKLISTED outright if the resource is blocked, or HEALTHY if it has no cells yet.
• score — the lowest score across the cells; null when there are none.
• recentWindow — success flags (oldest → newest) of the worst-scoring cell's window; an empty array when there are no cells. Severity and worst score are computed independently, so a row can read COOLING while showing the window of whichever context is dragging its score down.
• contexts — how many cells the resource holds. 0 means registered but never reported on.
• blockedUntil — the expiry of a temporary block; null when unblocked or permanent, so read it together with blockPermanent.

GET/api/pools/resources/{kind}/{value}

One resource expanded into its per-context cells, sorted by context.

{
  "kind": "PROXY",
  "value": "proxy-1.example.net:8080",
  "registered": true,
  "blocked": false,
  "blockedUntil": null,
  "blockPermanent": false,
  "cells": [
    {
      "context": "checkout-us",
      "score": -34.0,
      "consecutiveFailures": 2,
      "consecutiveSuccesses": 0,
      "windowSize": 10,
      "state": "COOLING",
      "cooldownUntil": "2026-07-29T10:41:02Z",
      "updatedAt": "2026-07-29T09:41:02Z"
    },
    {
      "context": "search-eu",
      "score": 35.0,
      "consecutiveFailures": 0,
      "consecutiveSuccesses": 7,
      "windowSize": 10,
      "state": "HEALTHY",
      "cooldownUntil": null,
      "updatedAt": "2026-07-29T09:44:18Z"
    }
  ]
}

Errors. 400 invalid resource kind or value for an unknown kind or a blank value. 404 resource not found when the pool has never seen this resource — that is, it has no cells, is not registered, and is not blocked.

GET/api/pools/resources/{kind}/{value}/score-history

The resource's sampled score curve, one ascending-time series per context. This is what the dashboard's 24-hour chart draws.

{
  "contexts": [
    {"context": "checkout-us",
     "points": [{"at":"2026-07-29T08:00:00Z","score":15.0},
                {"at":"2026-07-29T08:01:00Z","score":-15.0}]},
    {"context": "search-eu",
     "points": [{"at":"2026-07-29T08:00:00Z","score":30.0}]}
  ]
}

Scores are sampled on a timer (once a minute), not written on every report, so the curve is a sampled view rather than a full history of outcomes. An unknown resource returns 200 with an empty contexts array — there is simply no series. Samples are retained for seven days; see FAQ.

POST/api/pools/resources/{kind}/{value}/block

Blocklists a resource — the operator override that isolates it from selection in every context at once. Returns 204 No Content.

curl -sS -X POST "https://$RP_HOST/api/pools/resources/proxy/proxy-1/block?seconds=7200" \
  -H "Authorization: Bearer $RP_JWT"

curl -sS -X POST "https://$RP_HOST/api/pools/resources/proxy/proxy-1/block?permanent=true" \
  -H "Authorization: Bearer $RP_JWT"

The block emits RESOURCE_BLOCKLISTED, so it lands in the audit trail and the live stream with the rest of the timeline. Blocking an already-blocked resource replaces the entry. 400 for an invalid kind or value.

DELETE/api/pools/resources/{kind}/{value}/block

Releases a resource from the blocklist. Returns 204 No Content, and emits RESOURCE_UNBLOCKED only if it really was blocked — so unblocking something that is not blocked is a harmless no-op rather than a phantom audit entry. 400 for an invalid kind or value.

Releasing does not reset reputation. The resource returns to selection with its cells exactly as they were, so a cell that is still cooling stays benched for its own context until its cooldown expires.

GET/api/events

One page of your tenant's audit trail, newest first, with keyset (cursor) pagination — the cost of a page is flat no matter how far back you have scrolled.

{
  "events": [
    {"seq": 918, "eventType": "RESOURCE_COOLED", "resourceKind": "PROXY",
     "resourceValue": "proxy-1.example.net:8080", "context": "checkout-us",
     "occurredAt": "2026-07-29T09:41:02Z", "until": "2026-07-29T10:41:02Z", "cause": "BLOCKED"},
    {"seq": 917, "eventType": "RESOURCE_LEASED", "resourceKind": "PROXY",
     "resourceValue": "proxy-1.example.net:8080", "context": "checkout-us",
     "occurredAt": "2026-07-29T09:40:58Z", "until": "2026-07-29T09:41:28Z", "cause": null}
  ],
  "nextCursor": "OTE3"
}

Errors. 400 invalid cursor for a cursor you did not get from this endpoint. Do not construct cursors — the encoding is not part of the contract.

cursor=""
while :; do
  page=$(curl -sS "https://$RP_HOST/api/events?limit=500&cursor=$cursor" \
           -H "Authorization: Bearer $RP_JWT")
  echo "$page" | jq -c '.events[]'
  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

GET/api/usage

Your tenant's metered usage: the last 30 days of granted-lease counts, the current calendar month's total, and the most recently sampled pool size. Days are UTC.

{
  "monthLeaseTotal": 128400,
  "poolSize": 42,
  "dailyLeases": [
    {"date": "2026-07-28", "count": 5120},
    {"date": "2026-07-29", "count": 3980}
  ]
}

A lease is counted when it is granted, so an Acquire that returned granted: false does not count. Counts are accumulated in memory and flushed on a timer (once a minute), so the current day's number trails live traffic slightly. Days with no activity are absent from the array rather than present with a zero.

POST/api/tenants/{tenantId}/api-keys

Mints a data-plane API key. Returns 201 Created. The body is optional; omit it for an unlabelled key.

{"label":"worker-01"}

{
  "id": "5f1c2b40-…",
  "rawToken": "rp_9Q3xK7bT…",
  "label": "worker-01",
  "prefix": "rp_9Q3xK7bT",
  "createdAt": "2026-07-29T09:12:44Z"
}

GET/api/tenants/{tenantId}/api-keys

All of the tenant's keys, oldest first — never key material, only the non-secret display prefix. A non-null revokedAt means the key no longer authenticates.

[
  {"id":"5f1c2b40-…","label":"worker-01","prefix":"rp_9Q3xK7bT",
   "createdAt":"2026-07-29T09:12:44Z","revokedAt":null}
]

DELETE/api/tenants/{tenantId}/api-keys/{keyId}

Revokes an active key by its id. Returns 204 No Content. Effective immediately — the next gRPC call with that key fails.

Errors. 404 api key not found covers all three of "unknown id", "already revoked", and "belongs to another tenant", without distinguishing them.