Execute

Status: Developer preview — contract-stable per @nexislabs/ai-platform v1; not yet serving public traffic.

Contract note. The design spec (§3.1) describes this endpoint’s body as task, context, tools, policy, delivery plus a mode discriminator. The only published wire schema for this surface, AiPlatformChatRequestV1 (@nexislabs/ai-platform), has no mode, task, context, policy, or delivery keys, and is declared .strict() — a request carrying those keys today fails validation against that schema. tools and the idempotency key are the only vocabulary confirmed in both sources. This page documents both layers separately and labels which is which.

​

Two execution shapes, one contract

​

Endpoint

POST /v1/execute

​

Authentication

Authorization: Bearer praxa_sk_live_xxxxxxxxxxxxxxxxxxxx

​

Headers

​

Request body — design-spec envelope

​

Request body — mode:"turn" (published contract)

​

ClientInfo

​

Message

​

MessagePart

​

ToolsFilter

​

ApprovalReceipt

​

MemoryPolicy

​

OutputPolicy

​

Metadata

​

Idempotency

• Supply a key via the Idempotency-Key header or the body’s idempotencyKey field. The reference client prefers the header/option value over the body field when both are set.
• Idempotency keys are principal-scoped — two different API-key principals may reuse the same key value without colliding.
• Replaying the same key with an identical request is safe: the run’s first event, request.accepted, carries replayed: true.
• Replaying the same key with a different request body is a conflict: the server rejects it with error code conflict (see Errors).
• A separate code, idempotency_replay, also exists in the shared error-code enum. Neither source clarifies how it relates to the request.accepted.replayed signal above — flagged as an open question.

​

Response

• mode:"turn": text/event-stream — a stream of events.
• mode:"task": JSON. The design spec confirms only that a run identifier (run_id) is returned immediately; the full response schema is not published. Poll or stream progress via GET /v1/runs/:id or GET /v1/runs/:id/events.

​

Errors

​

Example

curl https://api.praxa.io/v1/execute \
  -X POST \
  -H "Authorization: Bearer praxa_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-AI-Platform-Version: v1" \
  -H "Idempotency-Key: 2026-07-30-example-001" \
  -N \
  -d '{
    "apiVersion": "v1",
    "requestId": "req_01j9example000000000000001",
    "client": { "kind": "external", "name": "acme-integration", "version": "1.0.0" },
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "parts": [{ "type": "text", "text": "Summarize this quarters open support tickets." }]
      }
    ]
  }'

​

TypeScript

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

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

for await (const event of client.streamChat({
  apiVersion: "v1",
  requestId: crypto.randomUUID(),
  client: { kind: "backend", name: "acme-integration", version: "1.0.0" },
  messages: [
    { id: "msg_001", role: "user", parts: [{ type: "text", text: "Summarize open tickets." }] },
  ],
})) {
  switch (event.type) {
    case "text.delta":
      process.stdout.write(event.delta);
      break;
    case "approval.required":
      // Render event.summary verbatim, obtain a decision, then POST it
      // back via /v1/runs/:id/approve with the matching action_digest.
      break;
    case "response.final":
      console.log(`\n[done: ${event.finishReason}]`);
      break;
  }
}