Skip to main content
POST
/
api
/
v1
/
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>"
}
'

​
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 -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"
  }'
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 -N http://127.0.0.1:8765/api/v1/runs/job-abc123/stream
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

StatusDescription
pendingJob submitted, waiting to start
runningJob is executing
succeededJob completed successfully
failedJob failed with error
cancelledJob was cancelled

​
Errors

StatusDescription
202Job accepted
200Success
204Deleted
400Invalid request
404Job not found
409Conflict (job not complete or still running)
500Server 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