Skip to content

What the section «Test documentation» shows

GET
/v1/projects/{id}/test-docs/summary
curl --request GET \
--url https://beta-api.plune.ai/v1/projects/example/test-docs/summary \
--header 'Authorization: Bearer <token>'

The numbers of the section’s home and coverage page (#2742, ADR 0082 §1, §3, §4): the current test plan, the latest matrix version, the requirements with and without acceptance criteria and cases, the API catalog’s endpoints with and without cases (null without a catalog), the split the cases give against the one the plan promises, and where the cases come from. Read from what exists - nothing is stored. Anyone in the project, a reader too; another project’s is the 404 of one that does not exist.

id
required
string

The project’s id

The summary

Media type application/json

What the section «Test documentation» shows on its home and its coverage page (#2742, ADR 0082 §1, §3, §4), read from the entities that hold it: the test plan, the traceability matrix, the requirements, the API catalog and the cases. Live cases only - a case in the Bin is not counted.

object
testPlan
required

The current version; null before the first save. split: what the plan promises, per cent

object
version
required
integer
>= 1
savedBy
required
string
savedAt
required
string format: date-time
versions
required
integer
>= 1
risks
required
integer
split
required
object
api
required
integer
ui
required
integer
manual
required
integer
matrix
required

The latest saved version of the traceability matrix; null - none yet

object
id
required

Stable: it names this snapshot for good, so a link can point at it (#1266).

string format: uuid
number
required

V1, v2, … within the project; a number is never reused.

integer
>= 1
periodFrom
required

The start of the period the coverage was counted over.

string format: date-time
periodTo
required

The end of the period, included.

string format: date-time
builtAt
required

When the snapshot was saved.

string format: date-time
authorName
required

Whoever saved it: their name, or their address when they have none; as it was then.

string
requirements
required

Archived requirements left out. failing and notRun by the health of their cases. needWork: up to 5, failing first, then without cases, not run, partly passing, passing

object
total
required
integer
withAcceptanceCriteria
required
integer
withoutAcceptanceCriteria
required
integer
withoutCases
required
integer
failing
required
integer
notRun
required
integer
needWork
required
Array<object>
<= 5 items
object
id
required
string format: uuid
key
required

The requirement’s short name (REQ-214), unique in the project, case-insensitive. Generated (REQ-<n>, per project, a number is never reused) or supplied. Never only digits, never an id.

string
/^[A-Za-z0-9._-]{1,40}$/
projectId
required
string
type
required
string
Allowed values: user_story feature epic
status
required

Where the requirement stands. Archiving is separate (archivedAt) and keeps the status.

string
Allowed values: draft active done
title
required
string
>= 1 characters <= 200 characters
description
required

Plain text, at most 16384 bytes.

string
nullable
priority
required

A free short label (Must-have, High), not an enum. null - not set.

string
nullable >= 1 characters <= 40 characters
acceptanceCriteria
required

Markdown text. null - not set.

string
nullable <= 20000 characters
category
required

Which kind of requirement it is. null - not set.

string
nullable
Allowed values: functional non-functional other
coverage
required

How the linked cases stand, counted from their RESULTS, never from a flag: each live case once, under the status of its newest result in a run that is not in the Bin (newest by when the run was created) — the status the run counters count it under, so a muted case’s failure is muted. A case with no result is notRun; a case in the Bin is not counted. total is the sum of the rest; «N of M cases passed» is passed of total.

object
total
required

M — the live cases linked to the requirement.

integer
passed
required

N — the cases whose newest result is passed.

integer
failed
required
integer
broken
required
integer
blocked
required
integer
skipped
required
integer
muted
required

Muted cases whose newest result failed or broke.

integer
notRun
required

Cases with no result in a run that is not in the Bin.

integer
automated
required

Of total, the cases of kind automated — the numerator of «9 of 14 cases are automated»; the denominator is total.

integer
cases

Only in the list asked with ?cases=true; always in the one requirement’s page.

Array<object>
object
id
required
string
title
required
string
suiteId
required
string
nullable
priority
required
string
latestStatus
required

The status the coverage counted the case under; null — no result yet.

string
nullable
Allowed values: passed failed broken blocked skipped muted
latestRunId
required

The run that result is in; null — no result yet.

string
nullable
mcpTools

#2461: the MCP tools the case tests (PUT /v1/mcp-tools/{id}/cases), so a requirement reaches its tools through its cases. Absent in a matrix version saved before 0.1.89: a saved version is kept as it was.

Array<object>
object
id
required
string
name
required
string
serverId
required
string
serverName
required
string
healthMark

#2252: on every row of the list and on the one requirement’s page, not in the answer of a write nor in a matrix snapshot. null — health follows the results.

object
One of:
object
state
required
string
Allowed values: set
by
required

The id of the owner who set it.

string
at
required
string format: date-time
reason
required

null — none was given.

string
nullable <= 500 characters
was
required

How the linked cases stand, counted from their RESULTS, never from a flag: each live case once, under the status of its newest result in a run that is not in the Bin (newest by when the run was created) — the status the run counters count it under, so a muted case’s failure is muted. A case with no result is notRun; a case in the Bin is not counted. total is the sum of the rest; «N of M cases passed» is passed of total.

object
total
required

M — the live cases linked to the requirement.

integer
passed
required

N — the cases whose newest result is passed.

integer
failed
required
integer
broken
required
integer
blocked
required
integer
skipped
required
integer
muted
required

Muted cases whose newest result failed or broke.

integer
notRun
required

Cases with no result in a run that is not in the Bin.

integer
automated
required

Of total, the cases of kind automated — the numerator of «9 of 14 cases are automated»; the denominator is total.

integer
archivedAt
required

Set while the requirement is archived: out of the default list and out of every coverage filter; its links stay.

string format: date-time
nullable
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
api
required

The API catalog’s endpoints and how many have cases; null - the catalog has no endpoints, which is not 0 %. needWork: up to 5, by health as the requirements are (failing first, then without cases, not run, partly passing, passing), then the fewest cases

object
endpoints
required
integer
>= 1
withCases
required
integer
withoutCases
required
integer
needWork
required
Array<object>
<= 5 items
object
id
required
string
projectId
required
string
apiId
required

The API it belongs to (#2398); one endpoint a method and path shape within an API

string
method
required
string
Allowed values: GET PUT POST DELETE OPTIONS HEAD PATCH TRACE
path
required

A template, /orders/{orderId}; one endpoint a method and path shape, whatever its parameters are called

string
source
required

Where the catalog learnt of it; a description replaces traffic once one names it

string
Allowed values: spec code traffic manual
trust
required

derived - inferred from examples or traffic (x-cairn-derived); confirmed - a written spec or a person says so

string
Allowed values: confirmed derived
inSpec
required

A spec, the code or a person describes it - not only traffic. The drift tells its two sides apart by it

boolean
summary
required
string
nullable
auth
required

The auth scheme names it asks for; [] public, null not known

Array<string>
nullable <= 10 items
lastSeenAt
required

When traffic last showed it

string format: date-time
nullable
lastSeenEnvironment
required

Where traffic last showed it

string
nullable
createdBy
required
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
coverage
required

How many live cases test it; GET /v1/api-endpoints/{id} names them

integer
health
required

How its live cases stand by their newest results, in a requirement’s words: failing - one failed or broke; passing - all passed; partial - some passed; notRun - none passed; noCases - none

string
Allowed values: failing passing partial notRun noCases
split
required

The split the cases give, in cases: covering an endpoint - api; automated without one - ui; manual without one - manual. api is null without endpoints. An eval case is in none

object
api
required
integer
nullable
ui
required
integer
manual
required
integer
cases
required

Disjoint, fromCode + byAgent + byHand = total: from code first (source=code), then the origin for the rest (byAgent: ai-generated or ai-edited; byHand: manual). describedFromCode and stale are what source=described and source=stale list

object
total
required
integer
fromCode
required
integer
describedFromCode
required
integer
stale
required
integer
byAgent
required
integer
byHand
required
integer
Example
{
"testPlan": {
"version": 2,
"savedBy": "6f1c2b3a-0000-4000-8000-0000000000a2",
"savedAt": "2026-11-12T10:00:00.000Z",
"versions": 2,
"risks": 4,
"split": {
"api": 60,
"ui": 30,
"manual": 10
}
},
"matrix": null,
"requirements": {
"total": 22,
"withAcceptanceCriteria": 17,
"withoutAcceptanceCriteria": 5,
"withoutCases": 4,
"failing": 2,
"notRun": 3,
"needWork": []
},
"api": null,
"split": {
"api": null,
"ui": 783,
"manual": 421
},
"cases": {
"total": 1204,
"fromCode": 412,
"describedFromCode": 96,
"stale": 7,
"byAgent": 342,
"byHand": 450
}
}

No / invalid token or session

No such project, or you are not in it

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}