Submit a human pull request review
curl --request POST \
--url https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expected_head_sha": "<string>",
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"body": "<string>",
"comments": [
{
"body": "<string>",
"line": 2,
"path": "<string>"
}
]
}
'import requests
url = "https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews"
payload = {
"expected_head_sha": "<string>",
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"body": "<string>",
"comments": [
{
"body": "<string>",
"line": 2,
"path": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
expected_head_sha: '<string>',
idempotency_key: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
body: JSON.stringify('<string>'),
comments: [{body: JSON.stringify('<string>'), line: 2, path: '<string>'}]
})
};
fetch('https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'expected_head_sha' => '<string>',
'idempotency_key' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'body' => '<string>',
'comments' => [
[
'body' => '<string>',
'line' => 2,
'path' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews"
payload := strings.NewReader("{\n \"expected_head_sha\": \"<string>\",\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"body\": \"<string>\",\n \"comments\": [\n {\n \"body\": \"<string>\",\n \"line\": 2,\n \"path\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expected_head_sha\": \"<string>\",\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"body\": \"<string>\",\n \"comments\": [\n {\n \"body\": \"<string>\",\n \"line\": 2,\n \"path\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expected_head_sha\": \"<string>\",\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"body\": \"<string>\",\n \"comments\": [\n {\n \"body\": \"<string>\",\n \"line\": 2,\n \"path\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"author_is_bot": true,
"author_login": "<string>",
"body": "<string>",
"github_review_id": 4503599627370496,
"html_url": "<string>",
"state": "<string>",
"submitted_at": "2023-11-07T05:31:56Z"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Pull Requests
Submit a human pull request review
Submits a review (COMMENT, APPROVE or REQUEST_CHANGES, with inline comments) on a pull request as the caller's own GitHub user, never the app's, pinned to the head they inspected, and answers 201 with the review as GitHub reports it.
Use this tool when you need to:
- Approve a pull request, or request changes on it, as yourself
- Leave several inline comments on a pull request's lines in one review
- Make sure a verdict applies only to the commit that was actually read
Examples:
- POST /pull-requests/{pullRequestID}/github/reviews {"idempotency_key": "2b5d7c3a-1e4f-4a6b-8c9d-0e1f2a3b4c5d", "event": "APPROVE", "expected_head_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8"}
- POST /pull-requests/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/github/reviews {"idempotency_key": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "event": "REQUEST_CHANGES", "expected_head_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "body": "The retry loop never backs off.", "comments": [{"path": "apps/api/github/client.go", "line": 42, "side": "RIGHT", "body": "Add a backoff here."}]}
Hints:
- pullRequestID is the pull request's uuid and org_id an optional uuid naming the owning organization to act in, the org_id getPullRequest answers. Required: idempotency_key (a uuid), event (COMMENT, APPROVE or REQUEST_CHANGES) and expected_head_sha (exactly 40 lowercase hex characters); optional: body and comments.
- Each comment requires path, line (at least 1) and body, path and body each with a character other than space, tab, newline, form feed or carriage return, and takes side LEFT or RIGHT (RIGHT when omitted).
- The schema answers 422 for a missing, malformed or unknown field and a body that is not JSON is 400; the handler answers 422, before the key is claimed, for REQUEST_CHANGES without a body, COMMENT with neither body nor comments, and a path or comment body that is only whitespace.
- expected_head_sha must be the pull request's head as Aether's mirror holds it (merge_box.head_sha from getPullRequestGithub); a head that moved past it is a 409 head_moved and nothing is posted. The review is made at that commit, so inline comments anchor to it.
- The idempotency key is the caller's on this pull request and claimed before GitHub is called: a completed key replays its review, read back from GitHub as the caller, and a key whose attempt failed before GitHub posted the review, head_moved included, or never finished is burnt: 409 idempotency_key_conflict. A review GitHub posted whose verdict then failed to record answers 500, and a retry with the same key records the verdict and replays the review without posting again.
- Answers 201 with github_review_id (an integer from 1 to 9007199254740991), author_login, author_is_bot, state, body, submitted_at and html_url; the verdict is stored at once, so getPullRequestGithub's reviews and reviewers show it before the webhook lands, and its webhook reaches the author task as human feedback.
- GitHub's 422 (an inline comment outside the diff, or approving one's own pull request) is a 422 with its message, and any other GitHub failure a 502.
- Use createPullRequestReviewRun instead to ask Aether to review the pull request, and createPullRequestGithubComment for a top-level comment without a verdict.
- A member with a product role (owner, admin or member) in an owning organization of the pull request (one whose task published or reviewed it, or with a project on its repository) may call it while they keep GitHub access to its repository; GitHub judges the review against the caller's own permission.
- A viewer or billing member is refused with 403 org_role_insufficient and a suspended organization with 403 org_suspended, each when no other owning organization admits the caller, and an agent host's grant with 403 agent_host_route_not_allowed; 503 when the membership check is unavailable.
- A caller linked to the repository's installation whose GitHub authorization is missing or revoked is refused with 409 github_identity_required (reconnect GitHub), whether at the gate or during the write.
- A pull request that does not exist, one no organization of the caller owns, an org_id that does not own it and one whose repository the caller cannot see on GitHub (no link to its installation included) answer the same 404; omitting org_id while more than one owning organization admits the caller is a 422 org_id_required, and a GitHub access check that cannot run is a 500.
POST
/
pull-requests
/
{pullRequestID}
/
github
/
reviews
Submit a human pull request review
curl --request POST \
--url https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expected_head_sha": "<string>",
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"body": "<string>",
"comments": [
{
"body": "<string>",
"line": 2,
"path": "<string>"
}
]
}
'import requests
url = "https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews"
payload = {
"expected_head_sha": "<string>",
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"body": "<string>",
"comments": [
{
"body": "<string>",
"line": 2,
"path": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
expected_head_sha: '<string>',
idempotency_key: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
body: JSON.stringify('<string>'),
comments: [{body: JSON.stringify('<string>'), line: 2, path: '<string>'}]
})
};
fetch('https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'expected_head_sha' => '<string>',
'idempotency_key' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'body' => '<string>',
'comments' => [
[
'body' => '<string>',
'line' => 2,
'path' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews"
payload := strings.NewReader("{\n \"expected_head_sha\": \"<string>\",\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"body\": \"<string>\",\n \"comments\": [\n {\n \"body\": \"<string>\",\n \"line\": 2,\n \"path\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expected_head_sha\": \"<string>\",\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"body\": \"<string>\",\n \"comments\": [\n {\n \"body\": \"<string>\",\n \"line\": 2,\n \"path\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/pull-requests/{pullRequestID}/github/reviews")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expected_head_sha\": \"<string>\",\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"body\": \"<string>\",\n \"comments\": [\n {\n \"body\": \"<string>\",\n \"line\": 2,\n \"path\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"author_is_bot": true,
"author_login": "<string>",
"body": "<string>",
"github_review_id": 4503599627370496,
"html_url": "<string>",
"state": "<string>",
"submitted_at": "2023-11-07T05:31:56Z"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Authorizations
Query Parameters
The pull request's owning organization to act in: the org_id the PullRequest carries. Omitted, getPullRequest and the review page's operations (its review, file, head snapshot and stack) act in the owning organization getPullRequest ranks first, and a console operation refuses with 422 org_id_required when more than one of the caller's organizations owns the pull request.
Body
application/json
Response
Created