Skip to content

Plan a batch of pull request reviews, and start it unless start is false. Local mode only: the pending reviews post with the local user's GitHub credential.

POST
/pr-batches
curl --request POST \
--url https://example.com/api/v1/pr-batches \
--header 'Content-Type: application/json' \
--data '{ "urls": [ "example" ], "repo": "example", "requested": true, "parallel": 1, "again": true, "stages": [ "rubric" ], "start": true, "levels": [ "must" ], "attribution": "speccy" }'
Media typeapplication/json
object
urls

Pull request URLs. Give these or repo.

Array<string>
repo

A repo as owner/name. The batch takes each open pull request that is not a draft and changes a spec doc.

string
requested

With repo, only the pull requests where someone asked for your review.

boolean
parallel

How many pull requests run at the same time. The default is 3.

integer
>= 1 <= 10
again

Review a pull request again although it was reviewed at its head commit.

boolean
stages

The model stages to run. Absent means all; empty means lint only.

Array<string>
Allowed values: rubric grounding divergence coherence
start

False plans the batch and waits for startPrBatch. The default is true.

boolean
levels

The finding levels that go inline as comments. Absent means pr.levels of the .speccy.yaml that each review uses.

Array<string>
Allowed values: must should
attribution

None keeps the name of Speccy out of the pending reviews. Absent means pr.attribution of the .speccy.yaml that each review uses.

string
Allowed values: speccy none

The batch, with its pull requests and the cost estimate.

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"
}