Claim dirty snapshot paths

GET/api/prerender/claim

claimPrerenderSnapshots

Long-polls the prerender work queue and leases up to `limit` dirty snapshot paths. Returns an empty list when nothing becomes dirty within the wait window — the worker simply re-claims. Each unit carries a `dirty_seq` that MUST be quoted back on complete/fail; a completion at a stale value means a write landed mid-render and the path stays queued. Authenticates with the prerender worker token.

Requires authentication using a bearer token — see tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/prerender/claim' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN'

fetch

fetch("https://neosource.dev/api/prerender/claim", {
  method: "GET",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
  },
});

Query parameters

limit: Maximum units to hand back in one response. Server-capped.
integerint32
wait_timeout_secs: How long the server may hold the connection open waiting for work before answering with an empty list. Server-capped.
integerint32

Responses

200Leased work (possibly empty)

application/json

ClaimSnapshotsResponse

object

Claim result. An empty list means "nothing dirty within the wait window" — the worker simply re-claims.

snapshotsrequired

array

items

ClaimedSnapshotResponse

object

One unit of prerender work.

attemptsrequired: integerint32
Completed failures for this path so far; the attempt now being executed is `attempts + 1`. Surfaced so the worker can log a persistent failure rather than silently retrying forever.
dirty_seqrequired: integerint64
Opaque token to quote back on complete/fail. Do not interpret it.
oprequired: PrerenderOp
snapshot_pathrequired: string
Normalized, leading-slash path — e.g. `/alice/demo/pulls`.

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

`PrerenderOp`

string

What the prerender worker should do with a claimed snapshot path. `Purge` (D5) exists so a repo leaving public visibility can retract its snapshots through the same claim/lease/retry machinery as a render, without the Rust server ever gaining S3 *delete* rights — the worker already owns S3 mutation, and a purge inherits the retry the old fire-and-forget delete never had.

"render""purge"