Execute

Status: Durable task mode is available in the production partner preview at https://api.praxa.io/v1/execute. The public route is task-only.

The public handler exposes one execution mode:

Mode	Response	Use it for
`task`	`202` with a `RunResource`	Durable work you inspect, stream, or cancel later.

Request

POST /v1/execute
Authorization: Bearer praxa_sk_<64 lowercase hex characters>
Content-Type: application/json
X-AI-Platform-Version: v1
Idempotency-Key: incident-2026-07-31-001

{
  "apiVersion": "v1",
  "requestId": "req-incident-001",
  "mode": "task",
  "task": {
    "input": "Summarize the incident and propose the next safe action."
  },
  "idempotencyKey": "incident-2026-07-31-001"
}

The schema rejects unknown fields. Identity, tenant, billing account, roles, and policy authority come from the authenticated principal. You cannot assign them in the body. The active admission path caps task.input at 16,000 characters and accepts personal tenants only. It rejects mode: "turn", task.agentId, context, tools, policy, delivery, and every other unknown field before creating a task. Organization execution remains closed until organization-unit delegation can be proved at the execution boundary.

Top-level fields

Field	Required	Notes
`apiVersion`	Yes	Literal `v1`.
`requestId`	Yes	Caller correlation identifier, 1–128 characters.
`mode`	Yes	Literal `task`. Any other value returns `400 invalid_request`.
`task`	Yes	Strict object containing only `input`, from 1 to 16,000 characters.
`idempotencyKey`	No	Body alternative to the header.

Task response

Task mode returns a strict customer-safe run projection:

{
  "apiVersion": "v1",
  "run_id": "2f47a86e-72ce-4f27-8ff0-7dc0c959fd35",
  "requestId": "req-incident-001",
  "mode": "task",
  "status": "queued",
  "createdAt": "2026-07-31T12:00:00.000Z",
  "updatedAt": "2026-07-31T12:00:00.000Z",
  "links": {
    "self": "/v1/runs/2f47a86e-72ce-4f27-8ff0-7dc0c959fd35",
    "events": "/v1/runs/2f47a86e-72ce-4f27-8ff0-7dc0c959fd35/events"
  }
}

Run status is one of queued, running, awaiting_approval, completed, failed, or cancelled. The cancellation-reconciliation migration and compatible Workers are deployed, and separate production canaries have proved its pre-dispatch and provider-in-flight final-state branches. Internal reconcile_required projects as running, not as a new public status. It is non-terminal. The event stream stays open and emits run.progress with The run is reconciling an uncertain execution outcome. Do not retry or resubmit it. If reconciliation succeeds, another run.progress event says Run reconciliation completed; execution is resuming. Once the final-status canary clears, if Praxa cannot verify whether a committing action happened, the run becomes failed. Its failure uses code: "run_outcome_unknown", message A committing action may have happened, but the final outcome could not be verified. Do not retry automatically., and retryable: false. Ordinary failed, partial, and expired outcomes use code: "run_failed". The versioned resource schema reserves fields for approval, result, failure, and usage. The current source projector returns lifecycle timestamps, links, a generic customer-safe failure when needed, and verified text only when a completed agent-loop result passes the result schema, action-digest match, and verification verdict. After the source-ready approval refinement is activated, an exact recorded browser action can also return a digest-bound pendingApproval. It does not yet project:

unverified or structured results;
per-run usage totals.

It never includes executor leases, internal billing references, provider costs, margins, raw prompts, chain-of-thought, or tool arguments.

Unsupported chat and turn surfaces

mode: "turn" is outside the public request schema. Sending it to POST /v1/execute returns 400 invalid_request; it is not a capacity error and must not be retried unchanged. /v1/chat is not a routed public endpoint. The source repository contains candidate turn event schemas for offline contract work. They do not define a served route, SDK method, or activation promise.

Idempotency

If both the Idempotency-Key header and body field are present, they must be identical or the handler returns 409 conflict. Task execution then uses the header, otherwise the body field, otherwise requestId. Keys are unique within the authenticated tenant.

Same key and the same normalized request: return the existing run projection.
Same key and different request: return conflict.
Missing task-origin/idempotency storage: fail instead of executing without replay protection.

Generate one key per logical action and reuse it for network retries. Do not generate a new key for each attempt.

TypeScript

import { AiPlatformClient } from "@nexislabs/ai-platform";

const client = new AiPlatformClient({
  baseUrl: "https://api.praxa.io",
  accessToken: () => process.env.PRAXA_API_KEY ?? null,
});

const run = await client.execute({
  apiVersion: "v1",
  requestId: crypto.randomUUID(),
  mode: "task",
  task: { input: "Summarize open support tickets." },
  idempotencyKey: crypto.randomUUID(),
});

for await (const event of client.streamRunEvents(run.run_id)) {
  console.log(event.type, event.sequence);
}

Partner-preview boundaries

The production partner-preview endpoint supports the durable task contract documented on this page. Turn mode, /v1/chat, request-level overrides, organization execution, and approval mutations remain fail-closed. Exact recorded browser approvals remain pending production activation. Cancellation-reconciliation final states have passed separate production canaries. A cancellation request is cooperative: it does not imply rollback or guarantee that the returned run is already cancelled. See Status and roadmap for the remaining general-availability gates.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Request

Top-level fields

Task response

Unsupported chat and turn surfaces

Idempotency

TypeScript

Partner-preview boundaries

​Request

​Top-level fields

​Task response

​Unsupported chat and turn surfaces

​Idempotency

​TypeScript

​Partner-preview boundaries

Request

Top-level fields

Task response

Unsupported chat and turn surfaces

Idempotency

TypeScript

Partner-preview boundaries