Async Jobs API

HTTP API endpoints for submitting and managing long-running agent jobs

Submit long-running agent tasks and retrieve results asynchronously via HTTP API.

Quick Start

import httpx

API_URL = "http://127.0.0.1:8005"

# Submit job
response = httpx.post(f"{API_URL}/api/v1/runs", json={"prompt": "Analyze data"})
job = response.json()
job_id = job["job_id"]

# Check status
status = httpx.get(f"{API_URL}/api/v1/runs/{job_id}").json()

# Get result when complete
result = httpx.get(f"{API_URL}/api/v1/runs/{job_id}/result").json()
print(result["result"])

Start Server

python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory

Workflow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Submit    │────▶│  Poll/Stream│────▶│   Result    │
│   Job       │     │   Status    │     │   or Cancel │
└─────────────┘     └─────────────┘     └─────────────┘
     POST              GET                GET/POST
  /api/v1/runs    /api/v1/runs/{id}   /api/v1/runs/{id}/result
                  /api/v1/runs/{id}/stream
                                      /api/v1/runs/{id}/cancel

Endpoints

Submit Run

POST /api/v1/runs - Submit a new job

List Runs

GET /api/v1/runs - List all jobs

Get Status

GET /api/v1/runs/ - Get job status

Get Result

GET /api/v1/runs//result - Get job result

Stream Progress

GET /api/v1/runs//stream - SSE stream updates

Cancel Run

POST /api/v1/runs//cancel - Cancel a job

Delete Run

DELETE /api/v1/runs/ - Delete a job

Health Check

GET /health - Server health status

Key Features

• Idempotency: Use Idempotency-Key header to prevent duplicate job submissions
• Webhooks: Receive callbacks when jobs complete via webhook_url
• Session Grouping: Group related jobs with session_id
• SSE Streaming: Real-time progress updates via Server-Sent Events
• Polling: Use retry_after field for optimal polling intervals

Status Values

Status	Description
queued	Job waiting to start
running	Job in progress
succeeded	Job completed successfully
failed	Job failed with error
cancelled	Job was cancelled

Authentication

The async jobs API does not require authentication by default. Configure authentication in your server deployment as needed.

CLI Usage

# Submit a job
praisonai run submit "Your prompt here"

# Check status
praisonai run status <job_id>

# Get result
praisonai run result <job_id>

# Stream progress
praisonai run stream <job_id>

# List jobs
praisonai run list

# Cancel job
praisonai run cancel <job_id>

See Also

• Async Jobs Feature Guide
• CLI Async Jobs