Build a Praxa backend with Next.js

​

Prerequisites

• Next.js App Router with TypeScript
• Your application session helper
• A personal Praxa key with execute:write
• Node.js 20 or newer

​

1. Add the server-only client

import "server-only";
import { createHash } from "node:crypto";

const endpoint = "https://api.praxa.io/v1/execute";
const apiKey = process.env.PRAXA_API_KEY;

if (!apiKey) throw new Error("PRAXA_API_KEY is required");

export async function submitTask(input: {
  userId: string;
  requestId: string;
  task: string;
}) {
  const idempotencyKey =
    "next:" +
    createHash("sha256")
      .update(input.userId + "\0" + input.requestId)
      .digest("hex");

  return fetch(endpoint, {
    method: "POST",
    cache: "no-store",
    headers: {
      authorization: "Bearer " + apiKey,
      "content-type": "application/json",
      "idempotency-key": idempotencyKey,
    },
    body: JSON.stringify({
      apiVersion: "v1",
      requestId: idempotencyKey,
      mode: "task",
      task: { input: input.task },
      idempotencyKey,
    }),
  });
}

​

2. Add the Route Handler

import { submitTask } from "@/lib/praxa.server";

export async function POST(request: Request) {
  const session = await requireSession();
  const body = await request.json();

  if (
    typeof body.task !== "string" ||
    body.task.length < 1 ||
    body.task.length > 16_000 ||
    typeof body.requestId !== "string" ||
    body.requestId.length < 16 ||
    body.requestId.length > 128
  ) {
    return Response.json({ error: "Invalid request" }, { status: 400 });
  }

  const upstream = await submitTask({
    userId: session.user.id,
    requestId: body.requestId,
    task: body.task,
  });

  const payload = await upstream.json();
  return Response.json(payload, {
    status: upstream.status,
    headers: { "cache-control": "no-store" },
  });
}

​

3. Call it from the client

export async function startTask(task: string, requestId = crypto.randomUUID()) {
  const response = await fetch("/api/tasks", {
    method: "POST",
    credentials: "same-origin",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ task, requestId }),
  });
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

​

4. Test the boundary

1. No session returns 401 before the Praxa call.
2. Invalid input returns 400 before the Praxa call.
3. A valid request forwards one server-owned key and no browser-supplied owner.
4. Repeating the same user and request ID emits the same idempotency key.
5. Changing either value emits a different idempotency key.
6. The response uses Cache-Control: no-store.

​

Troubleshooting

​

Best practices

• Import server-only in credential-owning modules.
• Keep the key unprefixed and scan built client chunks for credential patterns.
• Authenticate and bound the body before calling Praxa.
• Rate-limit per application principal.
• Store the request ID with the draft before the first mutation.
• Add a server-owned run-read route instead of exposing the Praxa key.
• Test Node and edge runtimes separately if your deployment uses both.

​

Optimize for production

• Reuse one configured HTTP or SDK client per process and bound concurrent upstream work.
• Prefer durable admission plus asynchronous readback over holding application requests open.
• Cache only non-sensitive, tenant-scoped reads within their documented freshness window.
• Measure p50/p95 latency, admission-to-terminal time, retries, conflicts, and connection reuse before tuning.

​

Cleanup and next steps

1. Revoke the disposable Praxa key and require a later request to fail.
2. Remove synthetic application records and any temporary environment files.
3. Cancel or archive unresolved test runs according to the application policy.
4. Retain only redacted request, run, and verification identifiers needed for the test record.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?