Skip to content

Get a batch and the state of each of its pull requests.

GET
/pr-batches/{batchId}
curl --request GET \
--url https://example.com/api/v1/pr-batches/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0
batchId
required
string format: uuid

The batch.

Media typeapplication/json
object
id
required
string format: uuid
status
required
string
Allowed values: planned running done cancelled stopped
parallel
required
integer
source
required

What the batch took, such as a repo or a count of URLs.

string
created_at
required
string format: date-time
finished_at
string format: date-time
estimate
required
object
pulls
required

The pull requests the batch will review. A skipped one is not counted.

integer
docs
required
integer
calls
required

The model calls the cache cannot answer.

integer
tokens_in
required
integer format: int64
tokens_out
required
integer format: int64
cost_usd
required
number
priced
required

False when a role has no price, so cost_usd is not complete.

boolean
lint_only
required

True when no reviewer model is assigned, or the stages are empty.

boolean
items
required
Array<object>
object
repo
required
string
pull
required
integer
url
required
string
state
required
string
Allowed values: waiting reviewing posted skipped failed
reason
required

Why a pull request is skipped, or why it failed.

string
head_sha
required
string
comments
required

The comments Speccy added to the pending review.

integer
removed
required

Speccy’s comments that it removed from the pending review, because their finding is gone.

integer
review_url
required
string
docs
required
Array<object>
object
path
required

The spec doc, relative to the repo root.

string
verdict
required

Build_ready or not_build_ready, or empty when the review of the doc failed.

string
must
required
integer
should
required
integer
error
string
config

The .speccy.yaml that the review used.

object
source
required

Repo: the .speccy.yaml of the repo at the commit. local: the .speccy.yaml of the folder that this Speccy serves, because the repo has none at the commit. none: the repo and the folder have none.

string
Allowed values: repo local none
path
required

With repo, the file in the repo. With local, the file on this machine. With none, empty.

string
pr
required

The pr section of the .speccy.yaml that the review used.

object
inline_limit
required

The most inline comments per spec doc. 0 means the default of 15.

integer
levels
required

The finding levels that go inline as comments. Empty means the default: MUST findings, and SHOULD findings with a suggestion.

Array<string>
Allowed values: must should
attribution
required

None keeps the name of Speccy out of a pending review.

string
Allowed values: speccy none
Example
{
"status": "planned",
"items": [
{
"state": "waiting",
"config": {
"source": "repo",
"pr": {
"levels": [
"must"
],
"attribution": "speccy"
}
}
}
]
}

An error.

Media typeapplication/problem+json

RFC 9457 problem details with a stable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
code
required

A stable machine-readable error code.

string
Examplegenerated
{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example",
"code": "example"
}