curl --request POST \
--url https://api.outerlayer.ai/v1/work-items/{workItemId}/claim \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Outerlayer-App-Id: <api-key>' \
--data '
{
"host": "<string>",
"hostKey": "<string>",
"runnerProtocol": 123,
"seconds": 1073741823
}
'import requests
url = "https://api.outerlayer.ai/v1/work-items/{workItemId}/claim"
payload = {
"host": "<string>",
"hostKey": "<string>",
"runnerProtocol": 123,
"seconds": 1073741823
}
headers = {
"X-Outerlayer-App-Id": "<api-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Outerlayer-App-Id': '<api-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
host: '<string>',
hostKey: '<string>',
runnerProtocol: 123,
seconds: 1073741823
})
};
fetch('https://api.outerlayer.ai/v1/work-items/{workItemId}/claim', 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.outerlayer.ai/v1/work-items/{workItemId}/claim",
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([
'host' => '<string>',
'hostKey' => '<string>',
'runnerProtocol' => 123,
'seconds' => 1073741823
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Outerlayer-App-Id: <api-key>"
],
]);
$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.outerlayer.ai/v1/work-items/{workItemId}/claim"
payload := strings.NewReader("{\n \"host\": \"<string>\",\n \"hostKey\": \"<string>\",\n \"runnerProtocol\": 123,\n \"seconds\": 1073741823\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Outerlayer-App-Id", "<api-key>")
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.outerlayer.ai/v1/work-items/{workItemId}/claim")
.header("X-Outerlayer-App-Id", "<api-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"host\": \"<string>\",\n \"hostKey\": \"<string>\",\n \"runnerProtocol\": 123,\n \"seconds\": 1073741823\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.outerlayer.ai/v1/work-items/{workItemId}/claim")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Outerlayer-App-Id"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"host\": \"<string>\",\n \"hostKey\": \"<string>\",\n \"runnerProtocol\": 123,\n \"seconds\": 1073741823\n}"
response = http.request(request)
puts response.read_body{
"data": {
"branch": "<string>",
"createdAt": "<string>",
"expiresAt": "<string>",
"host": "<string>",
"id": "<string>",
"itemKey": "<string>",
"kind": "implement",
"repositories": [
{
"branch": "<string>",
"primary": true,
"repository": "<string>"
}
],
"coAuthor": {
"email": "<string>",
"name": "<string>"
},
"commitAuthor": {
"email": "<string>",
"name": "<string>"
},
"unreachable": [
{
"reason": "installation_suspended",
"repository": "<string>"
}
]
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "runner_upgrade_required",
"docs": "<string>",
"message": "<string>",
"minimum": 123
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Claim a work item
Records a lease for the named host and returns an item key for it. The body must carry runnerProtocol, at or above the gateway’s minimum, or the claim is refused with runner_upgrade_required (426) and no lease is recorded. A runner key that is not yet bound to a host key binds to the one in hostKey when the claim is signed by it; see the signature headers. A live lease held by another key is refused: claim_not_held (403) when it carries the same host name, work_item_claimed (409) otherwise. A claim by the key holding the lease extends it, keeping the same lease id, whatever host it sends. The answer names the repositories the build checks out, each with the branch it works on and the primary first, and the primary’s branch. A claim the build cannot own is refused and recorded as a lease already released as failed, which uses up the build request or amend trigger behind it: pull_request_from_fork, pull_request_on_default_branch, pull_request_ambiguous and pull_request_repository_not_connected and repository_not_reachable (422), and branch_claimed_elsewhere (409). Each names the repository it is about in repository. A runner below protocol 16 that claims an item in a factory with more than one connected repository is refused with runner_protocol_too_old (426), no lease is recorded, so the request stays available to a newer runner. On a gateway that holds GitHub App keys the answer also carries commitAuthor, the App’s bot account, and coAuthor when the member who asked for the build signed in with GitHub; the runner authors the build’s commits as the first and credits the second.
curl --request POST \
--url https://api.outerlayer.ai/v1/work-items/{workItemId}/claim \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Outerlayer-App-Id: <api-key>' \
--data '
{
"host": "<string>",
"hostKey": "<string>",
"runnerProtocol": 123,
"seconds": 1073741823
}
'import requests
url = "https://api.outerlayer.ai/v1/work-items/{workItemId}/claim"
payload = {
"host": "<string>",
"hostKey": "<string>",
"runnerProtocol": 123,
"seconds": 1073741823
}
headers = {
"X-Outerlayer-App-Id": "<api-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Outerlayer-App-Id': '<api-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
host: '<string>',
hostKey: '<string>',
runnerProtocol: 123,
seconds: 1073741823
})
};
fetch('https://api.outerlayer.ai/v1/work-items/{workItemId}/claim', 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.outerlayer.ai/v1/work-items/{workItemId}/claim",
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([
'host' => '<string>',
'hostKey' => '<string>',
'runnerProtocol' => 123,
'seconds' => 1073741823
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Outerlayer-App-Id: <api-key>"
],
]);
$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.outerlayer.ai/v1/work-items/{workItemId}/claim"
payload := strings.NewReader("{\n \"host\": \"<string>\",\n \"hostKey\": \"<string>\",\n \"runnerProtocol\": 123,\n \"seconds\": 1073741823\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Outerlayer-App-Id", "<api-key>")
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.outerlayer.ai/v1/work-items/{workItemId}/claim")
.header("X-Outerlayer-App-Id", "<api-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"host\": \"<string>\",\n \"hostKey\": \"<string>\",\n \"runnerProtocol\": 123,\n \"seconds\": 1073741823\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.outerlayer.ai/v1/work-items/{workItemId}/claim")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Outerlayer-App-Id"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"host\": \"<string>\",\n \"hostKey\": \"<string>\",\n \"runnerProtocol\": 123,\n \"seconds\": 1073741823\n}"
response = http.request(request)
puts response.read_body{
"data": {
"branch": "<string>",
"createdAt": "<string>",
"expiresAt": "<string>",
"host": "<string>",
"id": "<string>",
"itemKey": "<string>",
"kind": "implement",
"repositories": [
{
"branch": "<string>",
"primary": true,
"repository": "<string>"
}
],
"coAuthor": {
"email": "<string>",
"name": "<string>"
},
"commitAuthor": {
"email": "<string>",
"name": "<string>"
},
"unreachable": [
{
"reason": "installation_suspended",
"repository": "<string>"
}
]
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "runner_upgrade_required",
"docs": "<string>",
"message": "<string>",
"minimum": 123
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
Factory id the request is scoped to.
API key (sk_outerlayer_*)
Headers
HTTP Message Signature (RFC 9421) made with the runner key's host key: runner=:<base64>:.
The signature's covered components and parameters: runner=("@method" "@path" "@query" "content-digest");created=<unix seconds>;nonce="<random>";keyid="<host key fingerprint>";alg="ed25519".
RFC 9530 digest of the request body, always sent, including for a request with none: sha-256=:<base64>:.
Path Parameters
Body
Response
A lease is recorded for this host (new, or the caller's own extended).
Show child attributes
Show child attributes