Skip to content

Turn a reviewer's concern into one question for the author, on the section of the pull request's spec docs that it is about, in the reviewer's pending review. Local mode only.

POST
/pr-asks
curl --request POST \
--url https://example.com/api/v1/pr-asks \
--header 'Content-Type: application/json' \
--data '{ "url": "example", "concern": "example", "section": [ "example" ], "force": true, "attribution": "speccy" }'
Media typeapplication/json
object
url
required

The URL of the pull request.

string
concern
required

The reviewer’s concern, in their own words.

string
section

The heading path of the section, when the concern fits more than one.

Array<string>
force

Post the question although the doc already answers the concern.

boolean
attribution

None posts the question with no hidden marker. Absent means pr.attribution of the .speccy.yaml that the pull request review uses.

string
Allowed values: speccy none

What Speccy did with the concern.

Media typeapplication/json
object
status
required

Posted: the question is in the pending review. answered: the doc answers the concern, and Speccy posted nothing. unclear: the concern fits two sections equally, and Speccy posted nothing.

string
Allowed values: posted answered unclear
question
required
string
doc

The spec doc of the section, relative to the repo root.

string
heading_path
Array<string>
line

With place line, the line of the comment.

integer
place

With posted, where the question is. line: on its line. body: in the body of the review, because the line is not in the diff. file: on the whole file, because the line is not in the diff and GitHub does not let anyone edit a review body that started empty.

string
Allowed values: line body file
answer_quote

With answered, the text of the doc that answers the concern.

string
candidates

With unclear, the sections that fit.

Array<object>
object
doc
required
string
heading_path
required
Array<string>
review_url
string
Example
{
"status": "posted",
"place": "line"
}

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