Praison AI

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

python
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

bash
praisonai serve jobs --port 8005

Or, using uvicorn directly (factory mode):

bash
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/{job_id} – Get job status

 Get Result

GET /api/v1/runs/{job_id}/result – Get job result

 Stream Progress

GET /api/v1/runs/{job_id}/stream – SSE stream updates

 Cancel Run

POST /api/v1/runs/{job_id}/cancel – Cancel a job

 Delete Run

DELETE /api/v1/runs/{job_id} – 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

StatusDescription
queuedJob waiting to start
runningJob in progress
succeededJob completed successfully
failedJob failed with error
cancelledJob was cancelled

Authentication

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

CLI Usage

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