{
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "agent",
"id": "researcher"
},
"input": "Research the topic and summarize it.",
"config": {
"conversation_mode": "create_new",
"tools": [
{
"name": "read_document",
"description": "Reads a document.",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
}
}
],
"context": [
{
"type": "text",
"text": "Use the provided document."
}
],
"forwarded_props": {
"model": "provider/model"
}
}
}curl --request POST \
--url https://api.veryfront.com/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "task",
"id": "health-check"
}
}
'import requests
url = "https://api.veryfront.com/runs"
payload = {
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "task",
"id": "health-check"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
project_id: '00000000-0000-4000-8000-000000000001',
target: {type: 'task', id: 'health-check'}
})
};
fetch('https://api.veryfront.com/runs', 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.veryfront.com/runs",
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([
'project_id' => '00000000-0000-4000-8000-000000000001',
'target' => [
'type' => 'task',
'id' => 'health-check'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-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.veryfront.com/runs"
payload := strings.NewReader("{\n \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n \"target\": {\n \"type\": \"task\",\n \"id\": \"health-check\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-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.veryfront.com/runs")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n \"target\": {\n \"type\": \"task\",\n \"id\": \"health-check\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.veryfront.com/runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n \"target\": {\n \"type\": \"task\",\n \"id\": \"health-check\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "task",
"id": "health-check"
},
"input": null,
"output": null,
"created_at": "2026-10-02T10:00:00Z",
"updated_at": "2026-10-02T10:00:02Z",
"trigger": {
"type": "api_key",
"id": "key_example"
}
}Create run
Create a run.
{
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "agent",
"id": "researcher"
},
"input": "Research the topic and summarize it.",
"config": {
"conversation_mode": "create_new",
"tools": [
{
"name": "read_document",
"description": "Reads a document.",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
}
}
],
"context": [
{
"type": "text",
"text": "Use the provided document."
}
],
"forwarded_props": {
"model": "provider/model"
}
}
}curl --request POST \
--url https://api.veryfront.com/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "task",
"id": "health-check"
}
}
'import requests
url = "https://api.veryfront.com/runs"
payload = {
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "task",
"id": "health-check"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
project_id: '00000000-0000-4000-8000-000000000001',
target: {type: 'task', id: 'health-check'}
})
};
fetch('https://api.veryfront.com/runs', 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.veryfront.com/runs",
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([
'project_id' => '00000000-0000-4000-8000-000000000001',
'target' => [
'type' => 'task',
'id' => 'health-check'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-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.veryfront.com/runs"
payload := strings.NewReader("{\n \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n \"target\": {\n \"type\": \"task\",\n \"id\": \"health-check\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-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.veryfront.com/runs")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n \"target\": {\n \"type\": \"task\",\n \"id\": \"health-check\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.veryfront.com/runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n \"target\": {\n \"type\": \"task\",\n \"id\": \"health-check\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"project_id": "00000000-0000-4000-8000-000000000001",
"target": {
"type": "task",
"id": "health-check"
},
"input": null,
"output": null,
"created_at": "2026-10-02T10:00:00Z",
"updated_at": "2026-10-02T10:00:02Z",
"trigger": {
"type": "api_key",
"id": "key_example"
}
}Authorizations
Use a JWT bearer token or a Veryfront API key in the Authorization header.
Headers
1 - 128Body
- Option 1
- Option 2
- Option 3
Create a direct run with project_id, target:{type,id}, and optional input, or execute a saved schedule or webhook. Input is business data; configuration and execution settings are separate.
UUID of the project containing the execution definition or saved source.
Definition executed by this run.
Show child attributes
Show child attributes
Optional display title for the accepted run.
1 - 255Labels used to organize runs.
Show child attributes
Show child attributes
Business input passed to the definition unchanged; omitted input resolves to null.
Definition-specific configuration; business keys retain their spelling on every transport. Agent targets with conversation_id read agent_admission (AgentAdmissionConfig).
Show child attributes
Show child attributes
Execution overrides, separate from business input and configuration.
Show child attributes
Show child attributes
Canonical UUID of the authenticated runtime parent; ordinary users cannot assert parent authority.
Durable tool invocation on an agent parent; requires parent_run_id and excludes node_id.
1 - 128Started workflow node on the parent; requires parent_run_id and excludes tool_call_id.
1 - 128Conversation associated with an agent admission, when applicable.
Batch UUID associated with the accepted run.
Response
Run admitted. Project-owned runs need project.runs.write; conversation-owned runs need editor access on the conversation.
- Option 1
- Option 2
The full created run when readable by the caller; otherwise only its admission receipt. Replay uses the same caller visibility.
Unique run UUID.
Current execution state.
pending, running, waiting, completed, failed, cancelled Project containing the run.
Resolved execution definition.
Show child attributes
Show child attributes
Business input supplied when the run was created.
Final business output; null until successful finalization.
When the run was accepted.
When the resource last changed, including usage updates.
How execution was initiated.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
Show child attributes
Show child attributes
Failure details, present only when the run failed.
Show child attributes
Show child attributes
Display title, omitted when unset.
Labels used to organize runs.
Show child attributes
Show child attributes
Immediate parent run ID, present on child runs.
Top-level ancestor run ID, present on child runs.
When the first execution attempt started, omitted before execution.
When the run completed, failed or was cancelled.
Definition-specific execution configuration.
Show child attributes
Show child attributes
Resolved execution settings and diagnostics.
Show child attributes
Show child attributes
Pending control requests and the current wait.
Show child attributes
Show child attributes
Orchestration task ID, distinct from the execution definition.
1 - 200Conversation containing the run.
Conversation message that supplied the input.
Conversation message containing the result.
Batch containing the run.
Usage when available; unknown measurements are null.
Show child attributes
Show child attributes
Counts and usage across all descendant runs, excluding this run.
Show child attributes
Show child attributes
Files produced by the run.
Show child attributes
Show child attributes
Pinned schemas for business input and output; null means no declared schema.
Show child attributes
Show child attributes
Additional resource metadata.
Show child attributes
Show child attributes