Create a job
curl --request POST \
--url https://api.bonya.ai/v1/job \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"existing_sandbox_id": "<string>",
"new_sandbox": {
"template_id": "<string>",
"template_revision": 123,
"snapshot": "<string>",
"image": "<string>",
"name": "<string>",
"env": {},
"secret_sets": [
"<string>"
]
},
"command": [
"<string>"
],
"env": {},
"secret_sets": [
"<string>"
],
"working_dir": "<string>",
"stdin_b64": "<string>",
"command_timeout_seconds": 2,
"run_deadline_seconds": 2,
"disposition": "delete",
"wake_if_paused": false,
"wait": false
}
'import requests
url = "https://api.bonya.ai/v1/job"
payload = {
"name": "<string>",
"existing_sandbox_id": "<string>",
"new_sandbox": {
"template_id": "<string>",
"template_revision": 123,
"snapshot": "<string>",
"image": "<string>",
"name": "<string>",
"env": {},
"secret_sets": ["<string>"]
},
"command": ["<string>"],
"env": {},
"secret_sets": ["<string>"],
"working_dir": "<string>",
"stdin_b64": "<string>",
"command_timeout_seconds": 2,
"run_deadline_seconds": 2,
"disposition": "delete",
"wake_if_paused": False,
"wait": False
}
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({
name: '<string>',
existing_sandbox_id: '<string>',
new_sandbox: {
template_id: '<string>',
template_revision: 123,
snapshot: '<string>',
image: '<string>',
name: '<string>',
env: {},
secret_sets: ['<string>']
},
command: ['<string>'],
env: {},
secret_sets: ['<string>'],
working_dir: '<string>',
stdin_b64: '<string>',
command_timeout_seconds: 2,
run_deadline_seconds: 2,
disposition: 'delete',
wake_if_paused: false,
wait: false
})
};
fetch('https://api.bonya.ai/v1/job', 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.bonya.ai/v1/job",
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([
'name' => '<string>',
'existing_sandbox_id' => '<string>',
'new_sandbox' => [
'template_id' => '<string>',
'template_revision' => 123,
'snapshot' => '<string>',
'image' => '<string>',
'name' => '<string>',
'env' => [
],
'secret_sets' => [
'<string>'
]
],
'command' => [
'<string>'
],
'env' => [
],
'secret_sets' => [
'<string>'
],
'working_dir' => '<string>',
'stdin_b64' => '<string>',
'command_timeout_seconds' => 2,
'run_deadline_seconds' => 2,
'disposition' => 'delete',
'wake_if_paused' => false,
'wait' => false
]),
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.bonya.ai/v1/job"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"existing_sandbox_id\": \"<string>\",\n \"new_sandbox\": {\n \"template_id\": \"<string>\",\n \"template_revision\": 123,\n \"snapshot\": \"<string>\",\n \"image\": \"<string>\",\n \"name\": \"<string>\",\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ]\n },\n \"command\": [\n \"<string>\"\n ],\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ],\n \"working_dir\": \"<string>\",\n \"stdin_b64\": \"<string>\",\n \"command_timeout_seconds\": 2,\n \"run_deadline_seconds\": 2,\n \"disposition\": \"delete\",\n \"wake_if_paused\": false,\n \"wait\": false\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.bonya.ai/v1/job")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"existing_sandbox_id\": \"<string>\",\n \"new_sandbox\": {\n \"template_id\": \"<string>\",\n \"template_revision\": 123,\n \"snapshot\": \"<string>\",\n \"image\": \"<string>\",\n \"name\": \"<string>\",\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ]\n },\n \"command\": [\n \"<string>\"\n ],\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ],\n \"working_dir\": \"<string>\",\n \"stdin_b64\": \"<string>\",\n \"command_timeout_seconds\": 2,\n \"run_deadline_seconds\": 2,\n \"disposition\": \"delete\",\n \"wake_if_paused\": false,\n \"wait\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bonya.ai/v1/job")
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 \"name\": \"<string>\",\n \"existing_sandbox_id\": \"<string>\",\n \"new_sandbox\": {\n \"template_id\": \"<string>\",\n \"template_revision\": 123,\n \"snapshot\": \"<string>\",\n \"image\": \"<string>\",\n \"name\": \"<string>\",\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ]\n },\n \"command\": [\n \"<string>\"\n ],\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ],\n \"working_dir\": \"<string>\",\n \"stdin_b64\": \"<string>\",\n \"command_timeout_seconds\": 2,\n \"run_deadline_seconds\": 2,\n \"disposition\": \"delete\",\n \"wake_if_paused\": false,\n \"wait\": false\n}"
response = http.request(request)
puts response.read_body{
"run": {
"run_id": "<string>",
"status": "running",
"created_sandbox": true,
"cleanup_failed": true,
"available_actions": [
"cancel"
],
"name": "<string>",
"sandbox_id": "<string>",
"schedule_id": "<string>",
"started_at_unix_nanos": 123,
"finished_at_unix_nanos": 123,
"result": {
"exit_code": 123,
"signaled": true,
"timed_out": true,
"stdout_b64": "<string>",
"stderr_b64": "<string>",
"stdout_truncated": true,
"stderr_truncated": true,
"signal": 123
},
"failure": "<string>"
}
}{
"run_id": "<string>",
"already_running": true
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>"
}Jobs
Create a job
Run or start a job on a new or existing sandbox. wait=false (default) starts durably and returns run_id immediately; wait=true blocks for the result, bounded by the caller’s own request timeout.
POST
/
v1
/
job
Create a job
curl --request POST \
--url https://api.bonya.ai/v1/job \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"existing_sandbox_id": "<string>",
"new_sandbox": {
"template_id": "<string>",
"template_revision": 123,
"snapshot": "<string>",
"image": "<string>",
"name": "<string>",
"env": {},
"secret_sets": [
"<string>"
]
},
"command": [
"<string>"
],
"env": {},
"secret_sets": [
"<string>"
],
"working_dir": "<string>",
"stdin_b64": "<string>",
"command_timeout_seconds": 2,
"run_deadline_seconds": 2,
"disposition": "delete",
"wake_if_paused": false,
"wait": false
}
'import requests
url = "https://api.bonya.ai/v1/job"
payload = {
"name": "<string>",
"existing_sandbox_id": "<string>",
"new_sandbox": {
"template_id": "<string>",
"template_revision": 123,
"snapshot": "<string>",
"image": "<string>",
"name": "<string>",
"env": {},
"secret_sets": ["<string>"]
},
"command": ["<string>"],
"env": {},
"secret_sets": ["<string>"],
"working_dir": "<string>",
"stdin_b64": "<string>",
"command_timeout_seconds": 2,
"run_deadline_seconds": 2,
"disposition": "delete",
"wake_if_paused": False,
"wait": False
}
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({
name: '<string>',
existing_sandbox_id: '<string>',
new_sandbox: {
template_id: '<string>',
template_revision: 123,
snapshot: '<string>',
image: '<string>',
name: '<string>',
env: {},
secret_sets: ['<string>']
},
command: ['<string>'],
env: {},
secret_sets: ['<string>'],
working_dir: '<string>',
stdin_b64: '<string>',
command_timeout_seconds: 2,
run_deadline_seconds: 2,
disposition: 'delete',
wake_if_paused: false,
wait: false
})
};
fetch('https://api.bonya.ai/v1/job', 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.bonya.ai/v1/job",
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([
'name' => '<string>',
'existing_sandbox_id' => '<string>',
'new_sandbox' => [
'template_id' => '<string>',
'template_revision' => 123,
'snapshot' => '<string>',
'image' => '<string>',
'name' => '<string>',
'env' => [
],
'secret_sets' => [
'<string>'
]
],
'command' => [
'<string>'
],
'env' => [
],
'secret_sets' => [
'<string>'
],
'working_dir' => '<string>',
'stdin_b64' => '<string>',
'command_timeout_seconds' => 2,
'run_deadline_seconds' => 2,
'disposition' => 'delete',
'wake_if_paused' => false,
'wait' => false
]),
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.bonya.ai/v1/job"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"existing_sandbox_id\": \"<string>\",\n \"new_sandbox\": {\n \"template_id\": \"<string>\",\n \"template_revision\": 123,\n \"snapshot\": \"<string>\",\n \"image\": \"<string>\",\n \"name\": \"<string>\",\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ]\n },\n \"command\": [\n \"<string>\"\n ],\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ],\n \"working_dir\": \"<string>\",\n \"stdin_b64\": \"<string>\",\n \"command_timeout_seconds\": 2,\n \"run_deadline_seconds\": 2,\n \"disposition\": \"delete\",\n \"wake_if_paused\": false,\n \"wait\": false\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.bonya.ai/v1/job")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"existing_sandbox_id\": \"<string>\",\n \"new_sandbox\": {\n \"template_id\": \"<string>\",\n \"template_revision\": 123,\n \"snapshot\": \"<string>\",\n \"image\": \"<string>\",\n \"name\": \"<string>\",\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ]\n },\n \"command\": [\n \"<string>\"\n ],\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ],\n \"working_dir\": \"<string>\",\n \"stdin_b64\": \"<string>\",\n \"command_timeout_seconds\": 2,\n \"run_deadline_seconds\": 2,\n \"disposition\": \"delete\",\n \"wake_if_paused\": false,\n \"wait\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bonya.ai/v1/job")
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 \"name\": \"<string>\",\n \"existing_sandbox_id\": \"<string>\",\n \"new_sandbox\": {\n \"template_id\": \"<string>\",\n \"template_revision\": 123,\n \"snapshot\": \"<string>\",\n \"image\": \"<string>\",\n \"name\": \"<string>\",\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ]\n },\n \"command\": [\n \"<string>\"\n ],\n \"env\": {},\n \"secret_sets\": [\n \"<string>\"\n ],\n \"working_dir\": \"<string>\",\n \"stdin_b64\": \"<string>\",\n \"command_timeout_seconds\": 2,\n \"run_deadline_seconds\": 2,\n \"disposition\": \"delete\",\n \"wake_if_paused\": false,\n \"wait\": false\n}"
response = http.request(request)
puts response.read_body{
"run": {
"run_id": "<string>",
"status": "running",
"created_sandbox": true,
"cleanup_failed": true,
"available_actions": [
"cancel"
],
"name": "<string>",
"sandbox_id": "<string>",
"schedule_id": "<string>",
"started_at_unix_nanos": 123,
"finished_at_unix_nanos": 123,
"result": {
"exit_code": 123,
"signaled": true,
"timed_out": true,
"stdout_b64": "<string>",
"stderr_b64": "<string>",
"stdout_truncated": true,
"stderr_truncated": true,
"signal": 123
},
"failure": "<string>"
}
}{
"run_id": "<string>",
"already_running": true
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>"
}Authorizations
personalApiKeysupabaseJwt
Personal byk_ API key; user-principal, resolved to a tenant by org context.
Headers
Absent means server-generated, which provides no deduplication; only client-supplied keys dedupe.
Maximum string length:
255Org context. Omitted means the caller's personal organization. A well-formed non-member org is 404; malformed is 400.
Body
application/json
Exactly one of existing_sandbox_id and new_sandbox is required. Exactly one of command and script is required.
Optional human-readable name for this job.
Show child attributes
Show child attributes
A script the user wrote or uploaded. The body travels inline and is capped; a script larger than the cap is a program, and a program belongs in the template or fetched by the script itself.
Show child attributes
Show child attributes
Optional script executed after the sandbox is ready and before the job command or script. A non-zero exit stops the job.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Secret set names (see /v1/secret-sets).
Required range:
x >= 1Required range:
x >= 1What happens to a sandbox this run created when the run ends, however it ends. Not meaningful for an existing sandbox.
Available options:
delete, keep Applies to an existing sandbox only. False makes a paused target a failure rather than an implicit wake, which is a billable action the caller may not have intended.
false starts durably and returns immediately (202); true blocks for the result, bounded by the caller's own request timeout (200).
Response
wait=true and the run finished before the request timed out
Show child attributes
Show child attributes