Do my users need an Encevra account?

No. Your server calls the API with your key. Your users only see your product.

Can I call the API from the browser?

No. Keep the key on your server and pass results to the browser yourself.

How long does a run take?

Full Noetis runs currently take minutes, so use asynchronous runs with polling or signed webhooks.

Guide

How to embed document analysis in a SaaS product

Treat analysis as a background job: submit from your server, track the run, and render findings with their source passages and review status. Never block a request thread on it and never ship the key to the browser. Before you show any of this to your own customers, get a licensing agreement in place.

For product and engineering leads at software companies. Written by the Encevra engine team. Reviewed 2026-10-12.

The shape of the integration

Your application owns the user, the documents and the screen. The engine owns one job: reading supplied material against a question and returning structured findings. Keep that boundary sharp and the integration stays small.

User uploads or selects material in your product
Your server sends question and material with your API key
You store the run id against your own record
You poll or receive a signed webhook
You render the brief, the quotes and the status

Worked example: a legal review feature

Say your SaaS product lets a customer paste in a contract and a counterparty document and asks for a playbook comparison. This is the exact shape of request your server would send to POST /api/public/v1/panel. The material below is an authored sample, not a recorded run; it shows what you would submit and what kind of findings you should design your UI around.

Your server sends the question and material shown here, plus engine: "legal", with your API key in the Authorization header. The API returns 202 with a run_id immediately; your server never waits on the request thread. You store that run_id against your own record (the contract review your customer started) and poll or wait for the signed webhook.

Authored input example, not a recorded engine run

Question sent to the engine

Review this NDA against our playbook.

Material sent with it

PLAYBOOK: Term max 3 years. Mutual obligations only. Liability cap required. Governing law: New York.
NDA (Acme and Brightline, v2): 1. Confidential Information means all information disclosed by Acme. 2. Recipient (Brightline) shall protect Confidential Information for 7 years. 3. Brightline shall indemnify Acme for any losses without limit. 4. This Agreement is governed by the laws of Delaware. 5. Section 6 governs return of materials. (No Section 6 is included.) 6a. Term: this Agreement ends after 2 years.

Review tasks a run like this is expected to cover

Confirm whether the confidentiality term matches the playbook's 3 year maximum
Check whether obligations are mutual or one-sided
Flag the uncapped indemnity against the playbook's required liability cap
Flag the governing law clause against the playbook's required jurisdiction
Note any referenced section that is missing from the supplied document

Integration decisions you have to make

Sync vs async mode: use the default async mode and poll, or use mode: "sync" only for short internal tools where you can afford to hold a request open for up to a few minutes
Which engine profile: "noetis" for the full panel on long or high stakes material, "lite" when material is short and you want a faster, cheaper pass
Idempotency: always send an Idempotency-Key tied to your own job id so a retried request never starts a second paid run
Webhook vs polling: a webhook tells you to fetch; keep polling as the source of truth, since webhook delivery can fail
Where the key lives: only on your server or server function, never in a browser bundle or mobile app binary

Design for slow, honest results

Recorded development runs on the full panel have taken roughly 1.5 to 3 minutes; some take longer depending on material length and engine. Design the interface around a pending state with a notification, not a spinner. A run can end incomplete with stated reasons; show those reasons rather than hiding the run.

Concrete limits to design around

Material for the full Noetis engine is capped at 150,000 characters per run; the lite engine is capped at 40,000 characters
Runs are asynchronous and can take minutes, not seconds; plan your UI and any customer-facing SLA around that
Only released runs are charged under self-serve billing; incomplete and failed runs release their credit hold and are not charged, but they still cost your user time and attention
Live access to the engines is approval-gated; a new account starts on a sandbox tier with simulated responses until Encevra approves live access
Showing engine output to your own customers, rather than using it only inside your own team, needs a signed licensing agreement before launch

What you still build

Document storage, permissions, the review interface, how a user accepts or rejects a finding, and your own audit trail. The engine returns data for those surfaces; it does not supply them.

A rollout plan that keeps users' trust

Ship analysis behind a clear label first, to a small group of customers who upload the documents they already review by hand. Show every finding with its quote so they can compare it with their own reading.

Week 1: call the API from your server and store the full JSON response
Week 2: show findings with quotes and status labels in a side panel
Week 3: collect accept and reject decisions from reviewers
Week 4: decide from those decisions, not from demos, whether to widen access

Frequently asked questions

Do my users need an Encevra account?: No. Your server calls the API with your key. Your users only see your product.
Can I call the API from the browser?: No. Keep the key on your server and pass results to the browser yourself.
How long does a run take?: Full Noetis runs currently take minutes, so use asynchronous runs with polling or signed webhooks.