Submit Run API - PraisonAI

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"
  }'

import httpx

response = httpx.post(
    "http://127.0.0.1:8005/api/v1/runs",
    json={
        "prompt": "Analyze the quarterly sales data",
        "timeout": 3600,
        "webhook_url": "https://example.com/callback",
        "session_id": "project-alpha"
    },
    headers={"Idempotency-Key": "unique-key-123"}
)

job = response.json()
print(f"Job ID: {job['job_id']}")
print(f"Poll URL: {job['poll_url']}")

praisonai run submit "Analyze the quarterly sales data" \
  --idempotency-key unique-key-123 \
  --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"
}

{
  "job_id": "run_abc123",
  "status": "running",
  "message": "Job already exists with this idempotency key"
}

POST

api

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"
  }'

import httpx

response = httpx.post(
    "http://127.0.0.1:8005/api/v1/runs",
    json={
        "prompt": "Analyze the quarterly sales data",
        "timeout": 3600,
        "webhook_url": "https://example.com/callback",
        "session_id": "project-alpha"
    },
    headers={"Idempotency-Key": "unique-key-123"}
)

job = response.json()
print(f"Job ID: {job['job_id']}")
print(f"Poll URL: {job['poll_url']}")

praisonai run submit "Analyze the quarterly sales data" \
  --idempotency-key unique-key-123 \
  --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"
}

{
  "job_id": "run_abc123",
  "status": "running",
  "message": "Job already exists with this idempotency key"
}

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

Header	Description
`Location`	URL to poll for job status
`Retry-After`	Recommended 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"
  }'

import httpx

response = httpx.post(
    "http://127.0.0.1:8005/api/v1/runs",
    json={
        "prompt": "Analyze the quarterly sales data",
        "timeout": 3600,
        "webhook_url": "https://example.com/callback",
        "session_id": "project-alpha"
    },
    headers={"Idempotency-Key": "unique-key-123"}
)

job = response.json()
print(f"Job ID: {job['job_id']}")
print(f"Poll URL: {job['poll_url']}")

praisonai run submit "Analyze the quarterly sales data" \
  --idempotency-key unique-key-123 \
  --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"
}

{
  "job_id": "run_abc123",
  "status": "running",
  "message": "Job already exists with this idempotency key"
}

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

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

​Response

​Response Headers

​Idempotency

​Webhook Callback

​Error Responses

​See Also

Response

Response Headers

Idempotency

Webhook Callback

Error Responses

See Also