Run custom crew
curl --request POST \
--url https://api.example.com/api/crews/run/custom \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"crew_config": {
"agents": [
{
"id": "<string>",
"ref": {
"artifact_id": "<string>",
"version": "<string>"
},
"role": "",
"goal": "",
"backstory": ""
}
],
"tasks": [
{
"description": "<string>",
"agent_index": 0,
"expected_output": "",
"context": [
123
]
}
],
"id": "<string>",
"verbose": false,
"process": "sequential",
"layout": {},
"context_packs": [
{
"artifact_id": "<string>",
"version": "<string>",
"token_budget": 101
}
],
"repository": {
"repos": [
{
"artifact_id": "<string>",
"version": "<string>"
}
],
"branch_prefix": "nx1/",
"max_files": 5,
"max_lines": 200,
"may_open_pr": true,
"may_comment": false
}
},
"task_input": {}
}
'import requests
url = "https://api.example.com/api/crews/run/custom"
payload = {
"crew_config": {
"agents": [
{
"id": "<string>",
"ref": {
"artifact_id": "<string>",
"version": "<string>"
},
"role": "",
"goal": "",
"backstory": ""
}
],
"tasks": [
{
"description": "<string>",
"agent_index": 0,
"expected_output": "",
"context": [123]
}
],
"id": "<string>",
"verbose": False,
"process": "sequential",
"layout": {},
"context_packs": [
{
"artifact_id": "<string>",
"version": "<string>",
"token_budget": 101
}
],
"repository": {
"repos": [
{
"artifact_id": "<string>",
"version": "<string>"
}
],
"branch_prefix": "nx1/",
"max_files": 5,
"max_lines": 200,
"may_open_pr": True,
"may_comment": False
}
},
"task_input": {}
}
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({
crew_config: {
agents: [
{
id: '<string>',
ref: {artifact_id: '<string>', version: '<string>'},
role: '',
goal: '',
backstory: ''
}
],
tasks: [{description: '<string>', agent_index: 0, expected_output: '', context: [123]}],
id: '<string>',
verbose: false,
process: 'sequential',
layout: {},
context_packs: [{artifact_id: '<string>', version: '<string>', token_budget: 101}],
repository: {
repos: [{artifact_id: '<string>', version: '<string>'}],
branch_prefix: 'nx1/',
max_files: 5,
max_lines: 200,
may_open_pr: true,
may_comment: false
}
},
task_input: {}
})
};
fetch('https://api.example.com/api/crews/run/custom', 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.example.com/api/crews/run/custom",
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([
'crew_config' => [
'agents' => [
[
'id' => '<string>',
'ref' => [
'artifact_id' => '<string>',
'version' => '<string>'
],
'role' => '',
'goal' => '',
'backstory' => ''
]
],
'tasks' => [
[
'description' => '<string>',
'agent_index' => 0,
'expected_output' => '',
'context' => [
123
]
]
],
'id' => '<string>',
'verbose' => false,
'process' => 'sequential',
'layout' => [
],
'context_packs' => [
[
'artifact_id' => '<string>',
'version' => '<string>',
'token_budget' => 101
]
],
'repository' => [
'repos' => [
[
'artifact_id' => '<string>',
'version' => '<string>'
]
],
'branch_prefix' => 'nx1/',
'max_files' => 5,
'max_lines' => 200,
'may_open_pr' => true,
'may_comment' => false
]
],
'task_input' => [
]
]),
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.example.com/api/crews/run/custom"
payload := strings.NewReader("{\n \"crew_config\": {\n \"agents\": [\n {\n \"id\": \"<string>\",\n \"ref\": {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"role\": \"\",\n \"goal\": \"\",\n \"backstory\": \"\"\n }\n ],\n \"tasks\": [\n {\n \"description\": \"<string>\",\n \"agent_index\": 0,\n \"expected_output\": \"\",\n \"context\": [\n 123\n ]\n }\n ],\n \"id\": \"<string>\",\n \"verbose\": false,\n \"process\": \"sequential\",\n \"layout\": {},\n \"context_packs\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\",\n \"token_budget\": 101\n }\n ],\n \"repository\": {\n \"repos\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n }\n ],\n \"branch_prefix\": \"nx1/\",\n \"max_files\": 5,\n \"max_lines\": 200,\n \"may_open_pr\": true,\n \"may_comment\": false\n }\n },\n \"task_input\": {}\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.example.com/api/crews/run/custom")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"crew_config\": {\n \"agents\": [\n {\n \"id\": \"<string>\",\n \"ref\": {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"role\": \"\",\n \"goal\": \"\",\n \"backstory\": \"\"\n }\n ],\n \"tasks\": [\n {\n \"description\": \"<string>\",\n \"agent_index\": 0,\n \"expected_output\": \"\",\n \"context\": [\n 123\n ]\n }\n ],\n \"id\": \"<string>\",\n \"verbose\": false,\n \"process\": \"sequential\",\n \"layout\": {},\n \"context_packs\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\",\n \"token_budget\": 101\n }\n ],\n \"repository\": {\n \"repos\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n }\n ],\n \"branch_prefix\": \"nx1/\",\n \"max_files\": 5,\n \"max_lines\": 200,\n \"may_open_pr\": true,\n \"may_comment\": false\n }\n },\n \"task_input\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/crews/run/custom")
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 \"crew_config\": {\n \"agents\": [\n {\n \"id\": \"<string>\",\n \"ref\": {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"role\": \"\",\n \"goal\": \"\",\n \"backstory\": \"\"\n }\n ],\n \"tasks\": [\n {\n \"description\": \"<string>\",\n \"agent_index\": 0,\n \"expected_output\": \"\",\n \"context\": [\n 123\n ]\n }\n ],\n \"id\": \"<string>\",\n \"verbose\": false,\n \"process\": \"sequential\",\n \"layout\": {},\n \"context_packs\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\",\n \"token_budget\": 101\n }\n ],\n \"repository\": {\n \"repos\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n }\n ],\n \"branch_prefix\": \"nx1/\",\n \"max_files\": 5,\n \"max_lines\": 200,\n \"may_open_pr\": true,\n \"may_comment\": false\n }\n },\n \"task_input\": {}\n}"
response = http.request(request)
puts response.read_body{
"correlation_id": "<string>",
"status": "pending",
"message": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Crews
Run custom crew
Run a crew of registry agents without saving it as a template.
Every agent must be a pinned registry version (ref): personal agents
of your own or Global ones. Inline agent definitions are refused (422).
The custom crew returns a correlation_id that you can also poll using GET /api/events/{cid}
for real-time progress or GET /api/crews/results/{cid} for the
final result.
POST
/
api
/
crews
/
run
/
custom
Run custom crew
curl --request POST \
--url https://api.example.com/api/crews/run/custom \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"crew_config": {
"agents": [
{
"id": "<string>",
"ref": {
"artifact_id": "<string>",
"version": "<string>"
},
"role": "",
"goal": "",
"backstory": ""
}
],
"tasks": [
{
"description": "<string>",
"agent_index": 0,
"expected_output": "",
"context": [
123
]
}
],
"id": "<string>",
"verbose": false,
"process": "sequential",
"layout": {},
"context_packs": [
{
"artifact_id": "<string>",
"version": "<string>",
"token_budget": 101
}
],
"repository": {
"repos": [
{
"artifact_id": "<string>",
"version": "<string>"
}
],
"branch_prefix": "nx1/",
"max_files": 5,
"max_lines": 200,
"may_open_pr": true,
"may_comment": false
}
},
"task_input": {}
}
'import requests
url = "https://api.example.com/api/crews/run/custom"
payload = {
"crew_config": {
"agents": [
{
"id": "<string>",
"ref": {
"artifact_id": "<string>",
"version": "<string>"
},
"role": "",
"goal": "",
"backstory": ""
}
],
"tasks": [
{
"description": "<string>",
"agent_index": 0,
"expected_output": "",
"context": [123]
}
],
"id": "<string>",
"verbose": False,
"process": "sequential",
"layout": {},
"context_packs": [
{
"artifact_id": "<string>",
"version": "<string>",
"token_budget": 101
}
],
"repository": {
"repos": [
{
"artifact_id": "<string>",
"version": "<string>"
}
],
"branch_prefix": "nx1/",
"max_files": 5,
"max_lines": 200,
"may_open_pr": True,
"may_comment": False
}
},
"task_input": {}
}
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({
crew_config: {
agents: [
{
id: '<string>',
ref: {artifact_id: '<string>', version: '<string>'},
role: '',
goal: '',
backstory: ''
}
],
tasks: [{description: '<string>', agent_index: 0, expected_output: '', context: [123]}],
id: '<string>',
verbose: false,
process: 'sequential',
layout: {},
context_packs: [{artifact_id: '<string>', version: '<string>', token_budget: 101}],
repository: {
repos: [{artifact_id: '<string>', version: '<string>'}],
branch_prefix: 'nx1/',
max_files: 5,
max_lines: 200,
may_open_pr: true,
may_comment: false
}
},
task_input: {}
})
};
fetch('https://api.example.com/api/crews/run/custom', 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.example.com/api/crews/run/custom",
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([
'crew_config' => [
'agents' => [
[
'id' => '<string>',
'ref' => [
'artifact_id' => '<string>',
'version' => '<string>'
],
'role' => '',
'goal' => '',
'backstory' => ''
]
],
'tasks' => [
[
'description' => '<string>',
'agent_index' => 0,
'expected_output' => '',
'context' => [
123
]
]
],
'id' => '<string>',
'verbose' => false,
'process' => 'sequential',
'layout' => [
],
'context_packs' => [
[
'artifact_id' => '<string>',
'version' => '<string>',
'token_budget' => 101
]
],
'repository' => [
'repos' => [
[
'artifact_id' => '<string>',
'version' => '<string>'
]
],
'branch_prefix' => 'nx1/',
'max_files' => 5,
'max_lines' => 200,
'may_open_pr' => true,
'may_comment' => false
]
],
'task_input' => [
]
]),
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.example.com/api/crews/run/custom"
payload := strings.NewReader("{\n \"crew_config\": {\n \"agents\": [\n {\n \"id\": \"<string>\",\n \"ref\": {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"role\": \"\",\n \"goal\": \"\",\n \"backstory\": \"\"\n }\n ],\n \"tasks\": [\n {\n \"description\": \"<string>\",\n \"agent_index\": 0,\n \"expected_output\": \"\",\n \"context\": [\n 123\n ]\n }\n ],\n \"id\": \"<string>\",\n \"verbose\": false,\n \"process\": \"sequential\",\n \"layout\": {},\n \"context_packs\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\",\n \"token_budget\": 101\n }\n ],\n \"repository\": {\n \"repos\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n }\n ],\n \"branch_prefix\": \"nx1/\",\n \"max_files\": 5,\n \"max_lines\": 200,\n \"may_open_pr\": true,\n \"may_comment\": false\n }\n },\n \"task_input\": {}\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.example.com/api/crews/run/custom")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"crew_config\": {\n \"agents\": [\n {\n \"id\": \"<string>\",\n \"ref\": {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"role\": \"\",\n \"goal\": \"\",\n \"backstory\": \"\"\n }\n ],\n \"tasks\": [\n {\n \"description\": \"<string>\",\n \"agent_index\": 0,\n \"expected_output\": \"\",\n \"context\": [\n 123\n ]\n }\n ],\n \"id\": \"<string>\",\n \"verbose\": false,\n \"process\": \"sequential\",\n \"layout\": {},\n \"context_packs\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\",\n \"token_budget\": 101\n }\n ],\n \"repository\": {\n \"repos\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n }\n ],\n \"branch_prefix\": \"nx1/\",\n \"max_files\": 5,\n \"max_lines\": 200,\n \"may_open_pr\": true,\n \"may_comment\": false\n }\n },\n \"task_input\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/crews/run/custom")
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 \"crew_config\": {\n \"agents\": [\n {\n \"id\": \"<string>\",\n \"ref\": {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"role\": \"\",\n \"goal\": \"\",\n \"backstory\": \"\"\n }\n ],\n \"tasks\": [\n {\n \"description\": \"<string>\",\n \"agent_index\": 0,\n \"expected_output\": \"\",\n \"context\": [\n 123\n ]\n }\n ],\n \"id\": \"<string>\",\n \"verbose\": false,\n \"process\": \"sequential\",\n \"layout\": {},\n \"context_packs\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\",\n \"token_budget\": 101\n }\n ],\n \"repository\": {\n \"repos\": [\n {\n \"artifact_id\": \"<string>\",\n \"version\": \"<string>\"\n }\n ],\n \"branch_prefix\": \"nx1/\",\n \"max_files\": 5,\n \"max_lines\": 200,\n \"may_open_pr\": true,\n \"may_comment\": false\n }\n },\n \"task_input\": {}\n}"
response = http.request(request)
puts response.read_body{
"correlation_id": "<string>",
"status": "pending",
"message": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
OAuth2AuthorizationCodeBearerAPIKeyHeader
The access token received from the authorization server in the OAuth 2.0 flow.
Headers
Optional UUID for this run. If you omit it or send a non-UUID value, the server assigns one.
Body
application/json
Response
Successful Response
Response returned after a crew run starts.
Was this page helpful?

