Encevra

Developer guide

Asynchronous runs, polling and terminal states

POST to /api/public/v1/panel returns 202 with a run_id. Poll /api/public/v1/runs/:id at the returned interval until status is released, incomplete or failed. Send an Idempotency-Key so retries never start a second run.

For backend developers. Written by the Encevra engine team. Reviewed 2026-10-12.

Example (TypeScript, server side)

This is an example. Use environment variables for keys and keep the call on your server.

// Server side only. ENCEVRA_API_KEY never reaches the browser.
const res = await fetch("https://encevra.com/api/public/v1/panel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ENCEVRA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": jobId, // retries return the same run
  },
  body: JSON.stringify({ question, material, engine: "legal" }),
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { run_id, retry_after_seconds } = await res.json();

let run;
do {
  await new Promise((r) => setTimeout(r, (run?.retry_after_seconds ?? retry_after_seconds) * 1000));
  run = await (await fetch(`https://encevra.com/api/public/v1/runs/${run_id}`, {
    headers: { Authorization: `Bearer ${process.env.ENCEVRA_API_KEY}` },
  })).json();
} while (run.status === "queued" || run.status === "running");

// Terminal states: "released", "incomplete", "failed"
if (run.status === "released") showBrief(run);
else if (run.status === "incomplete") showWithWarning(run); // reasons are included
else showError(run);

Retries and cancellation

Repeating a request with the same Idempotency-Key returns the original run. DELETE /api/public/v1/runs/:id cancels a queued run; its credit hold is released and it is never charged.

Common mistakes

  • Polling faster than retry_after_seconds
  • Treating incomplete as failed and discarding findings
  • Retrying without an Idempotency-Key and starting duplicate runs
  • Calling the API from the browser

Frequently asked questions

What are the terminal states?
released, incomplete and failed.
How do I avoid duplicate runs?
Send the same Idempotency-Key on retries.
Polling or webhooks?
Either. Webhooks avoid polling; keep a poll as a backup.

Read next