Admit a minimal durable task

curl --request POST \
  --url https://api.praxa.io/v1/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiVersion": {},
  "requestId": "<string>",
  "mode": {},
  "task.input": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({apiVersion: {}, requestId: '<string>', mode: {}, 'task.input': '<string>'})
};

fetch('https://api.praxa.io/v1/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.praxa.io/v1/execute"

payload = {
    "apiVersion": {},
    "requestId": "<string>",
    "mode": {},
    "task.input": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "apiVersion": "v1",
  "run_id": "018f0000-0000-7000-8000-000000000001",
  "requestId": "request-id-demo-0001",
  "mode": "task",
  "status": "queued",
  "createdAt": "2026-08-13T12:00:00.000Z",
  "updatedAt": "2026-08-13T12:00:00.000Z",
  "links": {
    "self": "/v1/runs/018f0000-0000-7000-8000-000000000001",
    "events": "/v1/runs/018f0000-0000-7000-8000-000000000001/events"
  }
}

POST

execute

Admit a minimal durable task

curl --request POST \
  --url https://api.praxa.io/v1/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiVersion": {},
  "requestId": "<string>",
  "mode": {},
  "task.input": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({apiVersion: {}, requestId: '<string>', mode: {}, 'task.input': '<string>'})
};

fetch('https://api.praxa.io/v1/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.praxa.io/v1/execute"

payload = {
    "apiVersion": {},
    "requestId": "<string>",
    "mode": {},
    "task.input": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "apiVersion": "v1",
  "run_id": "018f0000-0000-7000-8000-000000000001",
  "requestId": "request-id-demo-0001",
  "mode": "task",
  "status": "queued",
  "createdAt": "2026-08-13T12:00:00.000Z",
  "updatedAt": "2026-08-13T12:00:00.000Z",
  "links": {
    "self": "/v1/runs/018f0000-0000-7000-8000-000000000001",
    "events": "/v1/runs/018f0000-0000-7000-8000-000000000001/events"
  }
}

Admit a durable Praxa task with a personal workspace API key, then verify the returned run through readback or reconnectable events.

Availability: Production partner preview. Required scope: execute:write.

Authenticate safely

Create a disposable personal workspace API key with exactly execute:write. Send it as Authorization: Bearer $PRAXA_API_KEY. A Gateway OAuth token, Supabase JWT, provider credential, or organization memory key is not interchangeable with this key. The hosted playground sends the credential from your browser session to the documented API through the configured playground proxy. Use test data, never share the key, and revoke it when the check ends.

Request fields

string

Must equal the body idempotencyKey when both are present. The effective key is header, body, then requestId.

X-AI-Platform-Version header parameter.

required

apiVersion request field.

string

required

requestId request field.

task

required

mode request field.

string

required

task.input request field.

string

idempotencyKey request field.

Runnable request examples

curl --fail-with-body -X POST 'https://api.praxa.io/v1/execute' \
  -H "Authorization: Bearer $PRAXA_API_KEY" \
  -H "Idempotency-Key: tutorial-task-2026-08-13" \
  -H "X-AI-Platform-Version: v1" \
  -H "Content-Type: application/json" \
  --data '{
  "apiVersion": "v1",
  "requestId": "tutorial-task-2026-08-13",
  "mode": "task",
  "task": {
    "input": "Summarize the incident and propose the next safe action."
  },
  "idempotencyKey": "tutorial-task-2026-08-13"
}'

const response = await fetch("https://api.praxa.io/v1/execute", {
  "method": "POST",
  "headers": {
    "Authorization": `Bearer ${process.env.PRAXA_API_KEY}`,
    "Idempotency-Key": "tutorial-task-2026-08-13",
    "X-AI-Platform-Version": "v1",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
    "apiVersion": "v1",
    "requestId": "tutorial-task-2026-08-13",
    "mode": "task",
    "task": {
      "input": "Summarize the incident and propose the next safe action."
    },
    "idempotencyKey": "tutorial-task-2026-08-13"
  })
});
const text = await response.text();
if (!response.ok) throw new Error(`${response.status}: ${text}`);
console.log(text ? JSON.parse(text) : { status: response.status });

import json
import os
from urllib import error, request

payload = json.dumps({
  "apiVersion": "v1",
  "requestId": "tutorial-task-2026-08-13",
  "mode": "task",
  "task": {
    "input": "Summarize the incident and propose the next safe action."
  },
  "idempotencyKey": "tutorial-task-2026-08-13"
}).encode()

req = request.Request(
    "https://api.praxa.io/v1/execute",
    method="POST",
    headers={
      "Authorization": f"Bearer {os.environ['PRAXA_API_KEY']}",
      "Idempotency-Key": "tutorial-task-2026-08-13",
      "X-AI-Platform-Version": "v1",
      "Content-Type": "application/json"
    },
    data=payload,
)
try:
    with request.urlopen(req, timeout=30) as response:
        text = response.read().decode()
        print(json.loads(text) if text else {"status": response.status})
except error.HTTPError as exc:
    raise RuntimeError(f"{exc.code}: {exc.read().decode()}") from exc

What success means

A 202 response proves durable admission or an exact idempotent replay. It does not prove that the task completed.

Successful response

202 — Durable task admitted or exact idempotent replay returned.

required

apiVersion response field.

string

required

run_id response field.

string

required

requestId response field.

task

required

mode response field.

required

Public lifecycle status. Internal cancelling and reconcile_required states project as running; reconciliation is not terminal.

string

required

createdAt response field.

string

required

updatedAt response field.

string

completedAt response field.

object

Present only when Praxa can derive the exact recorded browser action and bind it to the stored action digest. The summary contains the exact recorded instruction or steps followed by the target host.

object

Present only for schema-valid, digest-matched verified text.

object

failure response field.

object

required

links response field.

{
  "apiVersion": "v1",
  "run_id": "018f0000-0000-7000-8000-000000000001",
  "requestId": "request-id-demo-0001",
  "mode": "task",
  "status": "queued",
  "createdAt": "2026-08-13T12:00:00.000Z",
  "updatedAt": "2026-08-13T12:00:00.000Z",
  "links": {
    "self": "/v1/runs/018f0000-0000-7000-8000-000000000001",
    "events": "/v1/runs/018f0000-0000-7000-8000-000000000001/events"
  }
}

Handle failures

Response	Meaning	Safe action
`400 invalid_request`	The method, path, headers, query, or body failed strict validation.	Correct the request; do not retry unchanged input.
`401 authentication_failed`	The bearer key is missing, malformed, expired, or revoked.	Stop and replace the key through the authenticated console.
`403 authorization_failed`	The authenticated key lacks scope or tenant authority.	Request only the missing least-privilege scope; never substitute another tenant ID.
`409 conflict`	The same idempotency key was paired with different logical input or state.	Restore the original body or create a key for a genuinely new operation.
`429 rate_limited`	The principal exceeded a bounded rate.	Honor `retryAfterMs` or `Retry-After`, add jitter, and cap attempts.
retryable `5xx`	The server could not confirm a final response.	Reconcile reads or replay the exact keyed mutation before creating new work.

Example problem

{
  "type": "https://docs.praxa.io/problems/authorization-failed",
  "title": "Authorization failed",
  "status": 403,
  "code": "authorization_failed",
  "detail": "The API key does not grant the required scope.",
  "retryable": false
}

Verify the result

Save run_id and Location.
Read the run or consume events until a terminal state.
Replay the exact request with the same key and require the same logical run.

Retry, cleanup, and production use

Treat 401, 403, and 409 as authority or state signals, not generic retry prompts.
Reuse the idempotency key only for an exact retry of the same logical mutation.
For 429 or retryable 5xx responses, follow server retry guidance and keep a bounded attempt budget.
Move the request into a trusted application backend before production; never ship the Praxa key in browser or mobile code.
Revoke the disposable key, disable test webhooks, and erase disposable candidate data after validation.

Continue with API authentication, the failure and retry guide, and the end-to-end coverage matrix.

Last modified on August 14, 2026

Start here

Tasks, runs & usage

Webhooks

Memory candidates

Admit a minimal durable task

Authenticate safely

Request fields

Runnable request examples

What success means

Successful response

Handle failures

Verify the result

Retry, cleanup, and production use

​Authenticate safely

​Request fields

​Runnable request examples

​What success means

​Successful response

​Handle failures

​Verify the result

​Retry, cleanup, and production use

Authenticate safely

Request fields

Runnable request examples

What success means

Successful response

Handle failures

Verify the result

Retry, cleanup, and production use