Praison AI

Submit Run API

Submit a new async job for execution

Submit a new long-running agent task for asynchronous execution.

ParamField string

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

ParamField string

Must be application/json

ParamField string

The task prompt or instruction for the agent to execute.

ParamField string

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

ParamField 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.

ParamField object

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

ParamField string

Framework to use for execution. Defaults to praisonai.

ParamField integer

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

ParamField string

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

ParamField string

Group related jobs together with a session identifier.

Response

ResponseField string

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

ResponseField string

Initial job status, typically queued.

ResponseField string

ISO 8601 timestamp of job creation.

ResponseField string

URL to poll for job status updates.

ResponseField string

URL for SSE streaming of job progress.

Response Headers

HeaderDescription
LocationURL to poll for job status
Retry-AfterRecommended seconds before first poll
cURL
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"
  }'
Python
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 (recipe)
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"}
  }'
Python (recipe)
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"])
CLI
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
202 Accepted
{
  "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"
}
409 Conflict (Duplicate Idempotency Key)
{
  "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:

python
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:

json
{
  "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

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.

See Also