Jobs API

curl --request POST \
  --url http://127.0.0.1:8765/api/v1/runs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "<string>",
  "agent_file": "<string>",
  "agent_yaml": "<string>",
  "framework": "<string>",
  "config": {},
  "webhook_url": "<string>",
  "timeout": 123,
  "session_id": "<string>"
}
'

import requests

url = "http://127.0.0.1:8765/api/v1/runs"

payload = {
    "prompt": "<string>",
    "agent_file": "<string>",
    "agent_yaml": "<string>",
    "framework": "<string>",
    "config": {},
    "webhook_url": "<string>",
    "timeout": 123,
    "session_id": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    agent_file: '<string>',
    agent_yaml: '<string>',
    framework: '<string>',
    config: {},
    webhook_url: '<string>',
    timeout: 123,
    session_id: '<string>'
  })
};

fetch('http://127.0.0.1:8765/api/v1/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_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/api/v1/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([
    'prompt' => '<string>',
    'agent_file' => '<string>',
    'agent_yaml' => '<string>',
    'framework' => '<string>',
    'config' => [
        
    ],
    'webhook_url' => '<string>',
    'timeout' => 123,
    'session_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <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 := "http://127.0.0.1:8765/api/v1/runs"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"agent_file\": \"<string>\",\n  \"agent_yaml\": \"<string>\",\n  \"framework\": \"<string>\",\n  \"config\": {},\n  \"webhook_url\": \"<string>\",\n  \"timeout\": 123,\n  \"session_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	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("http://127.0.0.1:8765/api/v1/runs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"agent_file\": \"<string>\",\n  \"agent_yaml\": \"<string>\",\n  \"framework\": \"<string>\",\n  \"config\": {},\n  \"webhook_url\": \"<string>\",\n  \"timeout\": 123,\n  \"session_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/api/v1/runs")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"agent_file\": \"<string>\",\n  \"agent_yaml\": \"<string>\",\n  \"framework\": \"<string>\",\n  \"config\": {},\n  \"webhook_url\": \"<string>\",\n  \"timeout\": 123,\n  \"session_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

POST

api

runs

Jobs API

curl --request POST \
  --url http://127.0.0.1:8765/api/v1/runs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "<string>",
  "agent_file": "<string>",
  "agent_yaml": "<string>",
  "framework": "<string>",
  "config": {},
  "webhook_url": "<string>",
  "timeout": 123,
  "session_id": "<string>"
}
'

import requests

url = "http://127.0.0.1:8765/api/v1/runs"

payload = {
    "prompt": "<string>",
    "agent_file": "<string>",
    "agent_yaml": "<string>",
    "framework": "<string>",
    "config": {},
    "webhook_url": "<string>",
    "timeout": 123,
    "session_id": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    agent_file: '<string>',
    agent_yaml: '<string>',
    framework: '<string>',
    config: {},
    webhook_url: '<string>',
    timeout: 123,
    session_id: '<string>'
  })
};

fetch('http://127.0.0.1:8765/api/v1/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_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/api/v1/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([
    'prompt' => '<string>',
    'agent_file' => '<string>',
    'agent_yaml' => '<string>',
    'framework' => '<string>',
    'config' => [
        
    ],
    'webhook_url' => '<string>',
    'timeout' => 123,
    'session_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <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 := "http://127.0.0.1:8765/api/v1/runs"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"agent_file\": \"<string>\",\n  \"agent_yaml\": \"<string>\",\n  \"framework\": \"<string>\",\n  \"config\": {},\n  \"webhook_url\": \"<string>\",\n  \"timeout\": 123,\n  \"session_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	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("http://127.0.0.1:8765/api/v1/runs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"agent_file\": \"<string>\",\n  \"agent_yaml\": \"<string>\",\n  \"framework\": \"<string>\",\n  \"config\": {},\n  \"webhook_url\": \"<string>\",\n  \"timeout\": 123,\n  \"session_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/api/v1/runs")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"agent_file\": \"<string>\",\n  \"agent_yaml\": \"<string>\",\n  \"framework\": \"<string>\",\n  \"config\": {},\n  \"webhook_url\": \"<string>\",\n  \"timeout\": 123,\n  \"session_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

Jobs API

The Jobs API provides asynchronous job management for long-running agent tasks with progress tracking and streaming.

Overview

Jobs API enables:

Async job submission with immediate response
Job status polling
Progress streaming via SSE
Job cancellation and cleanup
Idempotency for safe retries

When to Use

Long-running tasks: Tasks that take more than a few seconds
Background processing: Fire-and-forget with status polling
Progress tracking: Real-time progress updates
Reliable execution: Idempotent submissions

Base URL + Playground

# Start jobs server (part of unified server)
praisonai serve unified --host 127.0.0.1 --port 8765

Base URL: http://127.0.0.1:8765

Authentication

Send the key with either header when PRAISONAI_JOBS_API_KEY is set.

# Authorization header
curl -H "Authorization: Bearer $JOBS_API_KEY" http://127.0.0.1:8765/api/v1/runs

# X-API-Key header
curl -H "X-API-Key: $JOBS_API_KEY" http://127.0.0.1:8765/api/v1/runs

/health is the only endpoint reachable without a key. Enable the key with PRAISONAI_JOBS_API_KEY — see Async Jobs Deployment.

Endpoints

POST /api/v1/runs

Submit a new job for async execution.

string

Optional key to prevent duplicate submissions

string

required

The prompt/query for the agent

string

Path to agents YAML file

string

Inline agents YAML content

string

default:"praisonai"

Framework to use: praisonai, crewai, autogen

object

Additional configuration

string

URL to POST results when complete

integer

default:"3600"

Timeout in seconds

string

Session ID for grouping jobs

curl -X POST http://127.0.0.1:8765/api/v1/runs \
  -H "Authorization: Bearer $JOBS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "prompt": "Research AI agents",
    "agent_file": "agents.yaml",
    "framework": "praisonai"
  }'

import requests

response = requests.post(
    "http://127.0.0.1:8765/api/v1/runs",
    headers={
        "Authorization": f"Bearer {JOBS_API_KEY}",
        "Idempotency-Key": "unique-key-123",
    },
    json={
        "prompt": "Research AI agents",
        "agent_file": "agents.yaml"
    }
)
job = response.json()
print(f"Job ID: {job['job_id']}")
print(f"Poll URL: {job['poll_url']}")

Response (202 Accepted):

{
  "job_id": "job-abc123",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z",
  "poll_url": "http://127.0.0.1:8765/api/v1/runs/job-abc123",
  "stream_url": "http://127.0.0.1:8765/api/v1/runs/job-abc123/stream"
}

Headers:

Location: URL to poll for status
Retry-After: Suggested seconds before first poll (default: 2)

GET /api/v1/runs

List jobs with optional filters.

string

Filter by status: pending, running, succeeded, failed, cancelled

string

Filter by session ID

integer

default:"1"

Page number

integer

default:"20"

Jobs per page (max 100)

curl "http://127.0.0.1:8765/api/v1/runs?status=running&page=1"

Response:

{
  "jobs": [
    {
      "job_id": "job-abc123",
      "status": "running",
      "progress_percentage": 45,
      "progress_step": "Analyzing data...",
      "created_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:30:02Z"
    }
  ],
  "total": 15,
  "page": 1,
  "page_size": 20
}

GET /api/v1/runs/

Get job status.

string

required

Job ID

curl http://127.0.0.1:8765/api/v1/runs/job-abc123

Response:

{
  "job_id": "job-abc123",
  "status": "running",
  "progress_percentage": 75,
  "progress_step": "Generating report...",
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:30:02Z"
}

GET /api/v1/runs//result

Get job result (only for completed jobs).

string

required

Job ID

curl http://127.0.0.1:8765/api/v1/runs/job-abc123/result

Response (200 OK):

{
  "job_id": "job-abc123",
  "status": "succeeded",
  "result": "Research findings on AI agents..."
}

Response (409 Conflict - not complete):

{
  "detail": "Job is not complete. Current status: running"
}

POST /api/v1/runs//cancel

Cancel a running job.

string

required

Job ID

curl -X POST http://127.0.0.1:8765/api/v1/runs/job-abc123/cancel

Response:

{
  "job_id": "job-abc123",
  "status": "cancelled"
}

DELETE /api/v1/runs/

Delete a completed job.

string

required

Job ID

curl -X DELETE http://127.0.0.1:8765/api/v1/runs/job-abc123

Response: 204 No Content

GET /api/v1/runs//stream

Stream job progress via SSE.

string

required

Job ID

curl -N http://127.0.0.1:8765/api/v1/runs/job-abc123/stream

import requests

response = requests.get(
    "http://127.0.0.1:8765/api/v1/runs/job-abc123/stream",
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())

const eventSource = new EventSource(
  "http://127.0.0.1:8765/api/v1/runs/job-abc123/stream"
);

eventSource.addEventListener("progress", (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.percentage}% - ${data.step}`);
});

eventSource.addEventListener("result", (event) => {
  const data = JSON.parse(event.data);
  console.log("Result:", data.result);
  eventSource.close();
});

SSE Events:

event: status
data: {"status": "running", "job_id": "job-abc123"}

event: progress
data: {"percentage": 25, "step": "Researching..."}

event: progress
data: {"percentage": 50, "step": "Analyzing..."}

event: progress
data: {"percentage": 100, "step": "Complete"}

event: result
data: {"result": "Research findings..."}

Job Status Values

Status	Description
`pending`	Job submitted, waiting to start
`running`	Job is executing
`succeeded`	Job completed successfully
`failed`	Job failed with error
`cancelled`	Job was cancelled

Errors

Status	Description
202	Job accepted
200	Success
204	Deleted
400	Invalid request
401	Missing or invalid API key
404	Job not found
409	Conflict (job not complete or still running)
500	Server error

Idempotency

Use Idempotency-Key header to prevent duplicate job submissions:

curl -X POST http://127.0.0.1:8765/api/v1/runs \
  -H "Idempotency-Key: my-unique-key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Research AI"}'

If the same key is used again, the existing job is returned instead of creating a new one.

Notes

Jobs are stored in memory by default
Configure persistent storage for production
Webhook notifications are optional
SSE streaming includes heartbeats every 5 seconds

A2U API - Event streaming
Recipe API - Sync recipe execution

​Jobs API

​Overview

​When to Use

​Base URL + Playground

​Authentication

​Endpoints

​POST /api/v1/runs

​GET /api/v1/runs

​GET /api/v1/runs/

​GET /api/v1/runs//result

​POST /api/v1/runs//cancel

​DELETE /api/v1/runs/

​GET /api/v1/runs//stream

​Job Status Values

​Errors

​Idempotency

​Notes

​Related

Jobs API

Overview

When to Use

Base URL + Playground

Authentication

Endpoints

POST /api/v1/runs

GET /api/v1/runs

GET /api/v1/runs/

GET /api/v1/runs//result

POST /api/v1/runs//cancel

DELETE /api/v1/runs/

GET /api/v1/runs//stream

Job Status Values

Errors

Idempotency

Notes

Related