Jobs API

Async job management API for long-running agent tasks

POST /api/v1/runs

Jobs API

cURL

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

Endpoints

POST /api/v1/runs

Submit a new job for async execution.

Idempotency-Key · string

Optional key to prevent duplicate submissions

prompt · string · required

The prompt/query for the agent

agent_file · string

Path to agents YAML file

agent_yaml · string

Inline agents YAML content

framework · string · default: "praisonai"

Framework to use: praisonai, crewai, autogen

config · object

Additional configuration

webhook_url · string

URL to POST results when complete

timeout · integer · default: "3600"

Timeout in seconds

session_id · string

Session ID for grouping jobs

curl

curl -X POST http://127.0.0.1:8765/api/v1/runs \
  -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={"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.

status · string

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

session_id · string

Filter by session ID

page · integer · default: "1"

Page number

page_size · 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.

job_id · 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).

job_id · 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.

job_id · 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.

job_id · 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.

job_id · string · required

Job ID

curl

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
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

Related

• A2U API - Event streaming
• Recipe API - Sync recipe execution