Queue a result for human review
const url = 'https://beta-api.plune.ai/v1/review-items';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"resultId":"6f1c2b3a-0000-4000-8000-0000000000e1","note":"Passed only on the retry — a flaky selector or a real race?"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://beta-api.plune.ai/v1/review-items \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "resultId": "6f1c2b3a-0000-4000-8000-0000000000e1", "note": "Passed only on the retry — a flaky selector or a real race?" }'A person queues a disputed result here. The Cairn ingest also queues entries, but they are PROPOSED CASES rather than results (#10, ADR-CI-03) and arrive through /v1/ingest/cairn. One item per result. A reader may propose here (#1440): the item is created pending and counts in the pending ceiling like any other; a reader whose body names another state or a rejectionCategory is refused 403, so a proposal can never be a verdict. Deciding stays with a paid seat.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Must be a result in your project.
Why this one is worth a look.
Example
{ "resultId": "6f1c2b3a-0000-4000-8000-0000000000e1", "note": "Passed only on the retry — a flaky selector or a real race?"}Responses
Section titled “ Responses ”Queued, pending
One entry of the review queue. Always starts pending; a reviewer moves it on.
object
Present on an entry disputing a RESULT. Exactly one of resultId, proposedCase and discoveredTest is present: an entry with two asks two questions at once, and one with none asks nothing.
Present on an entry proposing a new case. Mutually exclusive with the other two.
object
Content-derived identity; the dedup key.
object
What the pre-review checks found, written before the proposal was queued (#1289). It marks the proposal. Only placeholder stops anything: a proposal whose title, steps or expected result still holds {{...}}, [TODO]/[TBD]/[FIXME]/[XXX] (or the same in <...>) or a run of three or more underscores cannot be approved (409 naming the places), and that check is read off the reviewer’s edited version when there is one. Absent means nothing was found.
object
Where the rule is explained.
object
Absent means never executed — NOT “no result yet”. blocked: no answer from the target.
What a match resolves through. Absent is a normal proposal, not a degraded one: an agent that names no key gets an entry with no comparison, which is exactly what a genuinely new case gets.
An identifier another tool already uses for this test, so a report can find its case without anyone typing a Plune id. The order of kind is load-bearing: it is the ranking that decides which key wins when several match different cases.
object
The reviewer’s corrected version of the proposal (#1878), beside proposedCase, which stays what the agent said. Present only after an edit; approving the item makes the case from it. Left off the page of the listing (editedBy and editedAt stay).
object
The user id of whoever saved the version in editedCase.
When editedCase was saved.
Present on an entry reporting a test the caller RUNS and this project has no case for. Mutually exclusive with the other two.
object
The identity. Order does not matter — the server ranks them and the highest-ranked kind is what deduplication reads, so two adapters sending the same keys in a different order do not produce two entries about one test.
An identifier another tool already uses for this test, so a report can find its case without anyone typing a Plune id. The order of kind is load-bearing: it is the ranking that decides which key wins when several match different cases.
object
The reporter that found it, e.g. playwright.
Where the test lives, e.g. e2e/checkout.spec.ts:12. Required while everything descriptive is optional: an approved discovery becomes an automated case, and that shape needs a spec to point at.
What it did on this run, in the reporter’ own word.
The run that turned it up, once stored.
changes_requested (#1276): a reviewer asked the author for changes (changeRequest says what). It is the item’s own state, not a mark on a reviewer: it cannot be approved until the author re-submits, which puts the item back to pending.
Raised by every re-submission; absent is 1. An approval counts only for the revision it was given on.
The user ids asked to review the item - the project’s default reviewer, when they could be asked.
The default reviewer who was NOT asked because they no longer have the right to review - the list says who was passed over.
Who approved which revision; the policy’s approvalsRequired counts those of the current revision.
object
The open request for changes (present with state: changes_requested); the author’s re-submission clears it.
object
Present on every item rejected after R4, and absent forever on rejections stored before it — those are never migrated and must keep reading without error. An item that is pending or approved usually has none, but MAY still carry one: a rejection returned to review keeps the pair in the row as a draft, and the next move to rejected must supply it in the request anyway. Read it as “meaningful only while state is rejected”, not as “absent otherwise”.
Example
{ "schemaVersion": 1, "id": "6f1c2b3a-0000-4000-8000-0000000000b1", "resultId": "6f1c2b3a-0000-4000-8000-0000000000e1", "state": "pending", "note": "Passed only on the retry — a flaky selector or a real race?", "createdAt": "2026-09-16T09:12:04.151Z", "updatedAt": "2026-09-16T09:12:04.151Z"}Missing resultId or an invalid body
object
Example generated
{ "error": "example"}No / invalid token or session
A reader whose body asks for a state other than pending, or a read API token
object
Example generated
{ "error": "example"}Result not found or not yours
object
Example generated
{ "error": "example"}Already queued — the body carries the existing item id
object
Example generated
{ "error": "example"}Two refusals share this status, and what to do about them is opposite. Rate-limited — the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442, #2092): Retry-After carries the seconds until the window rolls over, and waiting that long is the way out. Quota reached — a ceiling on what the project holds (runs in the last 24 hours, test cases, items waiting in the review queue): { error, quota }. A retry straight away frees nothing, so do not loop on it; the message says what makes room — deleting cases, working the queue down, an operator raising the limit — and the run quota, a rolling 24 hours, frees its oldest runs as they age out. Tell the two apart by the body: a 429 whose body has a quota object is a quota, one without it is a throttle. quota carries kind, limit, used, remaining and resetsAt: the figures behind the sentence, and for the run quota the instant its oldest run ages out (#1258). Retry-After is sent on a quota only where there is such an instant (the run quota: the whole seconds, at least 1, until resetsAt); the case, review-queue and project quotas free only by an action, have resetsAt: null, and send no Retry-After. GET /v1/quotas reads the same figures without a refusal.
object
The body of a 429 that is a quota and not a throttle: the sentence, and the figures behind it.
object
What was reached and the way out.
object
The ceiling. A write that would take used past it is refused with 429.
What the project holds now, counted by the same query that refuses a write.
limit - used, never below 0.
When the oldest counted run ages out of the rolling 24 hours and a slot frees on its own. null for the two quotas only an action frees (delete cases, decide queue items), and for a run quota with no runs in the window.
Example
{ "quota": { "kind": "runsPerDay" }}Headers
Section titled “Headers ”Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one