Praxa Execution Fabric: Quickstart

This guide has two tracks. Track 1 calls a published custom agent. Track 2 starts a durable run through the production Execution Fabric partner preview.

Track 1: Call a published agent today

Status: Available today.

If you have published an agent on Praxa’s custom-agent platform, you already have a deployment-scoped custom-agent key. Use it to run that agent from your own backend.

Request

curl -X POST https://api.praxa.io/api/custom-agent-run \
  -H "Authorization: Bearer <custom-agent-deployment-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the last five support tickets for this customer.",
    "externalSessionId": "customer-482910"
  }'

const response = await fetch("https://api.praxa.io/api/custom-agent-run", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRAXA_AGENT_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Summarize the last five support tickets for this customer.",
    externalSessionId: "customer-482910",
  }),
});

if (!response.ok) {
  throw new Error(`Agent run failed: ${response.status}`);
}

const result = await response.json();

Notes

externalSessionId is yours to assign. Pass the same value for the same end user on every call and Praxa keeps that conversation isolated and continuous across calls. Use a distinct value per end user.
The key authenticates one specific agent deployment. Keep it on your backend. Never ship it to a browser or a mobile client.
If the agent tries to take an action that sends, schedules, changes, or purchases something through a connector, that action still requires approval under the same server-side rules as the in-app experience. A read-only question-and-answer agent will not hit this path.
These fields cover text execution. If your agent also uses knowledge ingestion, memory, or automations, those are separate endpoints in the custom-agent API.

Track 2: Your first `execute()` run

Status: Production partner preview. Admitted accounts can create a personal key in the current signed-in console. The portal’s email-link/OTP fragment callback, persisted browser session, durable legal gate, and canonical routing are deployed. The deep link remains pending its authenticated production-host canary.

The live preview accepts the minimal durable-task envelope. It returns 400 invalid_request for mode: "turn" and request-level agent, tool, policy, context, and delivery overrides. /v1/chat is not routed.

Start a run

curl -X POST https://api.praxa.io/v1/execute \
  -H "Authorization: Bearer praxa_sk_<64 lowercase hex characters>" \
  -H "Content-Type: application/json" \
  -H "X-AI-Platform-Version: v1" \
  -H "Idempotency-Key: 5f2b1e3a-2b3e-4a6d-9c1a-3a2b1e3a2b3e" \
  -d '{
    "apiVersion": "v1",
    "requestId": "req-competitor-001",
    "mode": "task",
    "task": { "input": "Research three competitors and draft a one-page comparison." },
    "idempotencyKey": "5f2b1e3a-2b3e-4a6d-9c1a-3a2b1e3a2b3e"
  }'

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.praxa.io/v1/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRAXA_SK_KEY}`,
    "Content-Type": "application/json",
    "X-AI-Platform-Version": "v1",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    apiVersion: "v1",
    requestId: crypto.randomUUID(),
    mode: "task",
    task: { input: "Research three competitors and draft a one-page comparison." },
    idempotencyKey,
  }),
});

if (!response.ok) {
  throw new Error(`Execute request failed: ${response.status}`);
}

const run = await response.json();
console.log(run.run_id, run.status);

Follow the durable task

The public request uses mode: "task". The call returns a run id immediately, and you follow progress with:

GET /v1/runs/:id: current state.
GET /v1/runs/:id/events: the same event stream, resumable with a Last-Event-ID header.
a signed-in portal or bearer webhook configuration when you want Praxa to push signed events instead of polling.

mode: "turn" is not part of this route’s public schema and returns 400 invalid_request. /v1/chat is not routed.

Resolving an approval

If a step needs sign-off, the event feed emits approval.required with a summary and an action_digest. Post the digest back with your decision:

curl -X POST https://api.praxa.io/v1/runs/2f47a86e-72ce-4f27-8ff0-7dc0c959fd35/approve \
  -H "Authorization: Bearer praxa_sk_<64 lowercase hex characters>" \
  -H "Content-Type: application/json" \
  -d '{ "action_digest": "...", "decision": "approve" }'

The public contract uses approve or deny. Exact browser-action approval refinements are source-ready and pending activation. Once active, Praxa accepts the decision only when the digest still matches the exact pending instruction or steps and target host. Missing, stale, mismatched, cross-tenant, or unsupported approval shapes remain fail-closed. See Concepts.

After the run

Read tenant-scoped metering with GET /v1/usage. The public run projection is deliberately narrower than Praxa’s internal receipt: it exposes verified text only when the stored result, action digest, and verification verdict agree.

What’s next

Read Concepts for the full vocabulary.
Read Overview for the product framing.
Want into the preview cohort? Contact us.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Praxa Execution Fabric: Quickstart

Track 1: Call a published agent today

Request

Notes

Track 2: Your first `execute()` run

Start a run

Follow the durable task

Resolving an approval

After the run

What’s next

​Track 1: Call a published agent today

​Request

​Notes

​Track 2: Your first execute() run

​Start a run

​Follow the durable task

​Resolving an approval

​After the run

​What’s next

Track 1: Call a published agent today

Request

Notes

Track 2: Your first `execute()` run

Start a run

Follow the durable task

Resolving an approval

After the run

What’s next