Submit Run API

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

curl -X POST http://127.0.0.1:8005/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "review todays merges",
    "recipe_name": "nightly-reviewer",
    "recipe_config": {"model": "gpt-4o-mini"}
  }'

import httpx

response = httpx.post(
    "http://127.0.0.1:8005/api/v1/runs",
    json={
        "prompt": "review todays merges",
        "recipe_name": "nightly-reviewer",
        "recipe_config": {"model": "gpt-4o-mini"},
    },
)
job = response.json()
print(job["job_id"])

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

curl -X POST http://127.0.0.1:8005/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "review todays merges",
    "recipe_name": "nightly-reviewer",
    "recipe_config": {"model": "gpt-4o-mini"}
  }'

import httpx

response = httpx.post(
    "http://127.0.0.1:8005/api/v1/runs",
    json={
        "prompt": "review todays merges",
        "recipe_name": "nightly-reviewer",
        "recipe_config": {"model": "gpt-4o-mini"},
    },
)
job = response.json()
print(job["job_id"])

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.

string

Unique key to prevent duplicate job submissions. If a job with this key already exists, the existing job is returned.

string

required

Must be application/json

string

required

The task prompt or instruction for the agent to execute.

string

Path to the agent configuration YAML file. Defaults to agents.yaml.

string

Name of an installed recipe to execute. Mutually exclusive with agent_file / agent_yaml. When set, the prompt field is passed to the recipe as its input data.

object

Recipe configuration overrides passed through to the recipe runtime (e.g. {"model": "gpt-4o-mini"}). Defaults to {}.

string

Framework to use for execution. Defaults to praisonai.

integer

Maximum execution time in seconds. Defaults to 3600 (1 hour).

string

URL to receive a callback when the job completes. The callback includes the job result.

string

Group related jobs together with a session identifier.

When both recipe_name and agent_file are provided, recipe_name wins — the executor takes the recipe branch first (praisonai/jobs/executor.py:_run_recipe). Provide one or the other, not both.

Response

string

required

Unique identifier for the submitted job (e.g., run_abc123).

string

required

Initial job status, typically queued.

string

required

ISO 8601 timestamp of job creation.

string

required

URL to poll for job status updates.

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

curl -X POST http://127.0.0.1:8005/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "review todays merges",
    "recipe_name": "nightly-reviewer",
    "recipe_config": {"model": "gpt-4o-mini"}
  }'

import httpx

response = httpx.post(
    "http://127.0.0.1:8005/api/v1/runs",
    json={
        "prompt": "review todays merges",
        "recipe_name": "nightly-reviewer",
        "recipe_config": {"model": "gpt-4o-mini"},
    },
)
job = response.json()
print(job["job_id"])

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

If recipe_name points at a recipe that isn’t installed, the job is created (returns 202), then transitions to failed with the resolver’s error in error. Poll /api/v1/runs/{job_id} to see it.

Deploy

Response

Response Headers

Idempotency

Webhook Callback

Error Responses

See Also

​Response

​Response Headers

​Idempotency

​Webhook Callback

​Error Responses

​See Also

Response

Response Headers

Idempotency

Webhook Callback

Error Responses

See Also