Ask the author for changes

POST

/v1/review-items/{id}/changes-requested

const url = 'https://beta-api.plune.ai/v1/review-items/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/changes-requested';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"note":"The steps do not say which card to use."}'
};

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/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/changes-requested \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "note": "The steps do not say which card to use." }'

A reviewer (#1276). The item’s state becomes changes_requested and the words go on it as changeRequest; the author’s re-submission of the same proposal puts it back to pending and clears the request, and an approval on the old text is gone. While it stands the item cannot be approved (409). A person cannot be the reviewer of the item they put in the queue (409), only a pending item can be asked about (409), and the project’s review policy must be on.

Authorizations

bearerAuth
cookieAuth

Parameters

Path Parameters

required

string format: uuid

Request Body^required

application/json

object

note

required

What has to change.

string

>= 10 characters <= 2000 characters

Examples

ask

Say what has to change

{
  "note": "The steps do not say which card to use."
}

Responses

200

The item, now changes_requested

application/json

One entry of the review queue. Always starts pending; a reviewer moves it on.

object

schemaVersion

required

integer

Allowed values: 1

required

string format: uuid

resultId

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.

string format: uuid

proposedCase

Present on an entry proposing a new case. Mutually exclusive with the other two.

object

stableId

required

Content-derived identity; the dedup key.

string

title

required

string

<= 300 characters

execution

required

string

Allowed values: auto manual

steps

required

Array<string>

>= 1 items <= 20 items

expected

required

string

<= 2000 characters

origin

required

One of:

object
object

object

runId

required

string

mode

required

string

Allowed values: explore design api

target

required

string

technique

string

<= 32 characters

priority

string

source

object

kind

required

string

Allowed values: url openapi-operation requirement pasted-text

value

required

string

>= 1 characters <= 100 characters

rationale

string

>= 1 characters <= 400 characters

lint

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.

Array<object>

object

rule

required

string

Allowed values: title-vague step-empty expected-vague duplicate-case duplicate-proposal placeholder

message

required

string

url

required

Where the rule is explained.

string

runCost

object

tokens

required

integer

cases

required

integer

verdict

Absent means never executed — NOT “no result yet”. blocked: no answer from the target.

string

Allowed values: passed failed blocked

externalKeys

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.

Array<object>

<= 32 items

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

kind

required

string

Allowed values: playwright-id path-title allure-history cairn-stable eval-id qase testrail testomat zephyr

value

required

string

<= 1024 characters

editedCase

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

title

required

string

<= 300 characters

steps

required

Array<string>

>= 1 items <= 20 items

expected

required

string

<= 2000 characters

editedBy

The user id of whoever saved the version in editedCase.

string

editedAt

When editedCase was saved.

string format: date-time

discoveredTest

Present on an entry reporting a test the caller RUNS and this project has no case for. Mutually exclusive with the other two.

object

keys

required

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.

Array<object>

>= 1 items <= 8 items

object

kind

required

string

Allowed values: playwright-id path-title allure-history cairn-stable eval-id qase testrail testomat zephyr

value

required

string

<= 1024 characters

title

required

string

<= 300 characters

source

required

The reporter that found it, e.g. playwright.

string

<= 32 characters

specRef

required

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.

string

<= 400 characters

rawStatus

What it did on this run, in the reporter’ own word.

string

<= 64 characters

platformRunId

The run that turned it up, once stored.

string

state

required

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.

string

Allowed values: pending changes_requested approved rejected

revision

Raised by every re-submission; absent is 1. An approval counts only for the revision it was given on.

integer

>= 1

reviewers

The user ids asked to review the item - the project’s default reviewer, when they could be asked.

Array<string>

defaultReviewerSkipped

The default reviewer who was NOT asked because they no longer have the right to review - the list says who was passed over.

string

approvals

Who approved which revision; the policy’s approvalsRequired counts those of the current revision.

Array<object>

object

userId

required

string

required

string format: date-time

revision

required

integer

changeRequest

The open request for changes (present with state: changes_requested); the author’s re-submission clears it.

object

required

string

required

string format: date-time

note

required

string

revision

required

integer

rejectionCategory

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”.

string

Allowed values: duplicate incorrect out-of-scope low-value not-testable other

note

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

Example

{
  "schemaVersion": 1,
  "proposedCase": {
    "execution": "auto",
    "origin": {
      "mode": "explore"
    },
    "source": {
      "kind": "url"
    },
    "lint": [
      {
        "rule": "title-vague"
      }
    ],
    "verdict": "passed",
    "externalKeys": [
      {
        "kind": "playwright-id"
      }
    ]
  },
  "discoveredTest": {
    "keys": [
      {
        "kind": "playwright-id"
      }
    ]
  },
  "state": "pending",
  "rejectionCategory": "duplicate"
}

400

No words

application/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

401

No / invalid token or session

403

A read-only member

404

Not found or not yours

application/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

409

The author, an item that is not pending, or review is off

application/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

429

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

application/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

Headers

Retry-After

integer

Seconds until the window rolls over

Ask the author for changes

Authorizations

Parameters

Path Parameters

Request Body required

Examples

Responses

200

Example

400

Example generated

401

403

404

Example generated

409

Example generated

429

Example generated

Headers

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated