Migrate from a direct provider API

Status: This is a partial migration path, not a drop-in replacement for OpenAI or Anthropic chat APIs. Current /v1/execute supports a strict minimal durable task only. Turn streaming, messages, caller-defined tools/context, model selection, policy overrides, BYO credentials, and mature receipts are unavailable.

Move a workload only if it can be expressed as durable work whose result you will inspect later. Keep direct provider calls for interactive chat, exact model/version control, provider beta features, caller-executed tools, or custom streaming UX.

Current request mapping

Direct provider requests usually include a model, messages, tools, and stream settings. The current Praxa request accepts none of those controls:

POST /v1/execute
Authorization: Bearer praxa_sk_...
Content-Type: application/json
X-AI-Platform-Version: v1
Idempotency-Key: incident-2026-08-01-v1

{
  "apiVersion": "v1",
  "requestId": "incident-2026-08-01-v1",
  "mode": "task",
  "task": {
    "input": "Summarize this incident description and propose the next safe action."
  },
  "idempotencyKey": "incident-2026-08-01-v1"
}

The handler rejects mode:"turn", task.agentId, context, tools, policy, and delivery. Do not delete an existing tool loop or approval system on the assumption that Praxa can replace it today.

Current lifecycle mapping

Direct-provider concern	Current Praxa durable task
Request accepted	`202` with a UUID `run_id` and `RunResource`
Incremental model text	Not available on the durable projector
Tool call deltas/results	Not available on the durable projector
Completion	`run.completed` and a terminal `completed` run
Failure	`run.failed` and a terminal `failed` run
Cancellation	Cooperative cancel request, followed until `run.cancelled` or another real terminal state
Reconnect	`GET /v1/runs/{run_id}/events` with `Last-Event-ID`
Usage	`GET /v1/usage`, backed by completed provider and settlement evidence

The source repository’s rich candidate turn union—text.delta, tool.proposed, response.final, and request.failed—is an offline schema, not the current durable event stream or a served SDK method.

Safe incremental migration

Choose a non-interactive workload with no dependency on caller-selected tools, local files, or a specific model.
Start the durable task with one idempotency key per logical request.
Store the returned UUID run_id.
Poll the run or consume its resumable SSE feed.
Treat only run.completed, run.failed, or run.cancelled as terminal.
Compare output quality, latency, and GET /v1/usage evidence with the existing provider path before moving more traffic.
Keep an explicit fallback while the API remains a partner preview.

Do not migrate these yet

interactive chat or turn-by-turn streaming;
custom tool execution or rich tool event rendering;
exact model pinning, provider selection, or BYO funding;
caller-provided context, tool allowlists, policy, budgets, or delivery;
organization-tenant execution;
workflows that require a mature policy/approval/verification receipt.

Automatic signed webhooks are active for admitted personal tenants. Exact digest-bound browser-action approvals remain pending. Cancellation final-state behavior has passed separate production canaries. None of these capabilities makes the unavailable turn, generic tool, or policy surfaces available.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Migrate from a direct provider API

Current request mapping

Current lifecycle mapping

Safe incremental migration

Do not migrate these yet

See also

​Current request mapping

​Current lifecycle mapping

​Safe incremental migration

​Do not migrate these yet

​See also

Current request mapping

Current lifecycle mapping

Safe incremental migration

Do not migrate these yet

See also