Skip to main content
POST
/
api
/
v1
/
runs
curl -X POST http://127.0.0.1:8005/api/v1/runs \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "prompt": "Analyze the quarterly sales data",
    "timeout": 3600,
    "webhook_url": "https://example.com/callback",
    "session_id": "project-alpha"
  }'

{
  "job_id": "run_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z",
  "poll_url": "http://127.0.0.1:8005/api/v1/runs/run_abc123",
  "stream_url": "http://127.0.0.1:8005/api/v1/runs/run_abc123/stream"
}
Submit a new long-running agent task for asynchronous execution.
​
Idempotency-Key
string
Unique key to prevent duplicate job submissions. If a job with this key already exists, the existing job is returned.
​
Content-Type
string
required
Must be application/json
​
prompt
string
required
The task prompt or instruction for the agent to execute.
​
agent_file
string
Path to the agent configuration YAML file. Defaults to agents.yaml.
​
framework
string
Framework to use for execution. Defaults to praisonai.
​
timeout
integer
Maximum execution time in seconds. Defaults to 3600 (1 hour).
​
webhook_url
string
URL to receive a callback when the job completes. The callback includes the job result.
​
session_id
string
Group related jobs together with a session identifier.

​
Response

​
job_id
string
required
Unique identifier for the submitted job (e.g., run_abc123).
​
status
string
required
Initial job status, typically queued.
​
created_at
string
required
ISO 8601 timestamp of job creation.
​
poll_url
string
required
URL to poll for job status updates.
​
stream_url
string
required
URL for SSE streaming of job progress.

​
Response Headers

HeaderDescription
LocationURL to poll for job status
Retry-AfterRecommended seconds before first poll
curl -X POST http://127.0.0.1:8005/api/v1/runs \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "prompt": "Analyze the quarterly sales data",
    "timeout": 3600,
    "webhook_url": "https://example.com/callback",
    "session_id": "project-alpha"
  }'

{
  "job_id": "run_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z",
  "poll_url": "http://127.0.0.1:8005/api/v1/runs/run_abc123",
  "stream_url": "http://127.0.0.1:8005/api/v1/runs/run_abc123/stream"
}

​
Idempotency

Use the Idempotency-Key header to ensure a job is only created once, even if the request is retried: 
import httpx

# Safe to retry - same key returns existing job
for attempt in range(3):
    try:
        response = httpx.post(
            "http://127.0.0.1:8005/api/v1/runs",
            json={"prompt": "Process data"},
            headers={"Idempotency-Key": "unique-operation-id"},
            timeout=10
        )
        break
    except httpx.TimeoutException:
        continue

​
Webhook Callback

When webhook_url is provided, the server sends a POST request to that URL when the job completes: 
{
  "job_id": "run_abc123",
  "status": "succeeded",
  "result": "Task output here",
  "duration_seconds": 45.2
}

​
Error Responses

StatusDescription
400Bad request - missing or invalid prompt
409Conflict - duplicate idempotency key
422Validation error - invalid request body
500Internal server error

​
See Also