Check a prior auth before you send it

Use it from your codeThe hosted API with your key, and prompts to paste into a coding agent

Self-host · your GPUs · recommended

Run it yourself, on request

The same open models and app, on 1x RTX PRO 6000 (96 GB) for Qwen3.8-27B; the policy reader, the decision clock and the signed record need no GPU.
Data never leaves your machines, and there are no Decosa charges.
One prompt for Claude Code or Codex assembles the whole stack.
Early access: the container images are not public yet and the source needs access; the prompt says how to ask.

Get the assembly prompt

Hosted · by Decosa

Get an API key

Call the prior-auth pre-check and packet API from your own code in minutes.
Every model answer carries a signed receipt.
Synthetic, public or test data only: real patient data belongs on your own hardware.

Build with it

Paste one of these into Claude Code, Codex or another coding agent. The first wires your project to the hosted API with your DECOSA_API_KEY. The second pulls our containers and runs the same stack on your own GPU, with no Decosa charges.

Base URL: https://api.decosa.ai
Auth: Authorization: Bearer $DECOSA_API_KEY (or a demo session token)
Tool id: prior-auth-check

Use the hosted API

# Decosa prior-auth pre-check: use the hosted API

You are wiring Decosa's prior-auth pre-check into this project. Before a prior-authorization request goes to the payer,
it takes the payer's own published medical policy (text or the PDF), the chart and the requested service, and returns a
check with a signed record. Every model call has a signed receipt. Use only what is listed below; if you need something
else, stop and ask me.

The check has:
- the criteria section it used (code-table rows removed; licensed criteria such as InterQual or MCG are never included);
- each criterion `met`, `not_met` or `undocumented`, with the policy quote and a chart quote found word for word, and the
  record to get when it's undocumented;
- a decision: `ready`, `gather_first`, `not_supported`, `proprietary_criteria` (the policy points to licensed criteria it
  can't check) or `review`;
- form answers with chart quotes, a peer-to-peer brief, and a letter of medical necessity only when the decision is `ready`.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- **Hosted use is for synthetic charts only.** Charts are protected health information: real patients belong on a
  self-hosted box (see the self-host prompt) or confidential access. Say so wherever this is wired in.
- This is a drafting aid. Never auto-submit, never type the values into a payer portal for the user (payer portals'
  terms generally forbid automation), never present the letter as final, and never tell a user the payer will approve.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in `DECOSA_API_KEY`, never in code.
   Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "prior-auth-check"}` returns `{"token", "expires_at", "budget"}`.
   A demo token runs one check at a time (409 otherwise); over a limit you get HTTP 429 with `Retry-After`.
3. A check needs about 12,000 generated tokens left in the budget before it starts (402 otherwise).

## Endpoints
- `POST /priorauth/check` (token). Body: `{"policy": {"title"?, "text" | "pdf_base64", "source"?, "section"?}, "records": [{"kind"?: "note"|"study"|"lab"|"imaging"|"order"|"letter"|"therapy"|"other", "title"?, "date"?, "text"}], "service", "codes"?: {"procedure": [...], "diagnosis": [...]}, "payer"?, "plan_type"?: "erisa_group"|"aca_individual"|"medicare_advantage"|"medicaid_mc"|"other", "urgent"?, "request_date"?: "YYYY-MM-DD", "form_questions"?: [string], "patient_ref"?}` or `{"sample_id": "..."}`.
  - Limits: 8 records of 12,000 characters each, 40,000 in total; a policy of 400,000 characters or a 12 MB PDF with a text
    layer; 20 form questions; codes only (a description is refused). URLs are not fetched.
  - The JSON response has `recommendation` `{decision, headline, why, requirements, missing: [{text, get, any_of}], not_met, confirm, guidance}`,
    `criteria` `[{id, text, quote, ref, group, kind?, status, evidence: [{ref, quote}], get?, note?}]`, `tree`, `policy`,
    `clock`, `form` `{standard, criteria, questions}`, `brief`, `letter` (or null), `letter_sentences`, `packet_md`, `record`,
    `record_check`, `usage` (calls, tokens, cost at list price), `receipts` and `note`.
  - With `Accept: text/event-stream` (or `"stream": true`), the events are `ready`, `policy`, `clock`, `criteria`, a
    `receipt` per model call, a `criterion` per criterion, `recommendation`, `form`, `brief`, a `sentence` per letter
    sentence, `letter`, then `result`, `budget` and `done`.
- `POST /priorauth/section` (token): the policy reader alone (which section of a long policy or PDF it would use).
- `POST /record/verify` (no token) `{"record": {...}}` returns `{ok, summary, checks, first_bad}`.
- `GET /priorauth/info`, `GET /priorauth/samples` and `GET /attest/signing-key` need no token.

## Example: check a request and act on the decision (Python, `pip install httpx`)
```python
import httpx, json, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
body = {"policy": {"title": "Payer policy", "text": open("policy-criteria.txt").read()},
        "records": json.load(open("chart.json")), "service": "MRI of the lumbar spine",
        "codes": {"procedure": ["72148"], "diagnosis": ["M54.16"]}, "plan_type": "erisa_group"}
r = httpx.post(f"{API}/priorauth/check", json=body, headers=H, timeout=900)
r.raise_for_status()
js = r.json()
print(js["recommendation"]["headline"])
for m in js["recommendation"]["missing"]:
    print("get first:", m["text"], "->", m["get"])
if js["letter"]:
    open("letter-of-medical-necessity.txt", "w").write(js["letter"])   # a draft: the clinician edits and signs it
open("prior-auth-check.md", "w").write(js["packet_md"])
json.dump(js["record"], open("prior-auth-check.json", "w"))           # keep with the request
```

Run it yourself (containers)

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa prior-auth pre-check: run it yourself (containers)

You are setting up the Decosa prior-auth pre-check on this machine, so charts never leave it. Before a request goes to the
payer, it reads the payer's published medical policy (text or PDF) and the chart, and returns:
- each criterion met, not met or not documented, with the policy and chart quotes, and the record to get;
- a decision (ready to send, get records first, not supported on this chart, or can't check licensed criteria);
- form answers with chart quotes, a peer-to-peer brief, and a letter of medical necessity only when every criterion is met.

It seals a signed record. Nothing is sent to Decosa's hosted API.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
"test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
https://decosa.ai/samples/prior-auth-check.zip (6 KB, 8 checks, synthetic or openly licensed: see `licence` in expected.json),
show me what is in it, and run the rehearsal against the local API:
`docker compose exec api python scripts/rehearse.py prior-auth-check` (the api image carries the same bundle under /app/rehearsal/prior-auth-check/;
with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
`python scripts/rehearse.py prior-auth-check --bundle prior-auth-check.zip --base-url http://127.0.0.1:<PORT>`.
It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the supported request is ready to send", "a letter of medical necessity is drafted and cites the AHI", "the unsupported request is not supported on this chart"). Show me
the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
instructions for this distribution (docs.docker.com/engine/install). Install the NVIDIA container toolkit, then check
`docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
`mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
Read it. Keep the `llm` service (Qwen3.8-27B on vLLM) and the `api` service. On the `api` service:
- set `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1` and `DECOSA_LLM_MODEL=qwen3.8-27b`;
- keep its data on a named volume;
- bind every port to 127.0.0.1.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check. The first start
downloads about 20 GB of weights.
4. Check: `curl -fsS http://127.0.0.1:<PORT>/priorauth/info` lists the decision-clock rules with their citations, links
and the date they were read. `GET /attest/signing-key` shows this box's public key.
5. Smoke test: get a token with `POST /demo/session {"vertical":"prior-auth-check"}`, then:
- `POST /priorauth/check {"sample_id": "cpap-ready"}`: expect `recommendation.decision` `ready` and a letter;
- `{"sample_id": "cpap-not-supported"}`: expect `not_supported` and `letter: null`;
- `{"sample_id": "proprietary-criteria"}`: expect `proprietary_criteria`;
- `POST /record/verify {"record": <record>}` should give `ok: true`, and every receipt should be `attested`.
6. Report back: the public key and key id, the smoke-test results, and how long each check took.

Run it on your own hardwareWhat it needs, and the prompt that sets it up

Run it on your own GPU

Same app, same pinned models, your hardware. Nothing goes to our servers and there are no Decosa charges.

Hardware check

Check your own hardware

CPU only, 64 GB RAMDoesn't fit
Qwen3.8-27B (NVIDIA NVFP4) needs a GPU.
GeForce RTX 4090standard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVIDIA NVFP4) with A community 4-bit build of Qwen3.8-27B (AWQ or GGUF). This build is NVIDIA NVFP4, which needs a Blackwell GPU. (Memory is an estimate.)
GeForce RTX 5090standard tierRuns
The standard tier fits with changes: Qwen3.8-27B (NVIDIA NVFP4): run it at its smallest setting (about 28 GB instead of 57.6 GB), with a shorter context and fewer parallel sessions.
2x GeForce RTX 5090standard tierRuns
The standard tier fits with changes: Split the language model across the GPUs with tensor parallelism (vLLM --tensor-parallel-size).
L40Sstandard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVIDIA NVFP4) with Qwen3.8-27B official FP8. This build is NVIDIA NVFP4, which needs a Blackwell GPU.
H100 80 GB (SXM)standard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVIDIA NVFP4) with Qwen3.8-27B official FP8. This build is NVIDIA NVFP4, which needs a Blackwell GPU.
RTX PRO 6000 Blackwell 96 GBstandard tierRuns
The standard tier fits (57.6 of 96 GB).
2x RTX PRO 6000 Blackwell 96 GBbest tierRuns
The standard tier fits (57.6 of 192 GB). The best tier fits too.
Apple M3 Ultra (Mac Studio), 96 GBstandard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVIDIA NVFP4) with Qwen3.8-27B MLX 4-bit. MLX build for Apple Silicon.
Apple M5 Max, 64 GBstandard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVIDIA NVFP4) with Qwen3.8-27B MLX 4-bit. MLX build for Apple Silicon.

Memory per component comes from measured footprints, the tool's stack.json, or an estimate from its parameter count, and each is labelled that way below. Only an RTX PRO 6000 and an M3 Ultra Mac Studio have actually been run.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

1
Check the GPU, Docker and the NVIDIA Container Toolkit
The driver must see the GPU, and Docker must be able to pass it into a container.
```
nvidia-smi
docker compose version
docker run --rm --gpus all ubuntu nvidia-smi
```
2
Fetch the compose file
One file describes the API and the language model as services.
```
mkdir -p ~/decosa && cd ~/decosa
curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml
```
3
Pull and start
The first start downloads pinned model weights, tens of gigabytes.
```
docker compose pull
docker compose up -d
```

4

Check health

Wait until the API reports ok with the language model loaded. Then point your app at the local base URL.

curl -fsS http://localhost:<PORT>/healthz
# {"ok": true, "llm": true, ...}
curl -fsS -X POST http://localhost:<PORT>/demo/session \
  -H 'Content-Type: application/json' -d '{"vertical":"prior-auth-check"}'

Set up with a coding agent, rehearse on mock data, then go private

Set up with a coding agent. Paste the self-host prompt into a coding agent on the machine that will run the service. We recommend Claude Code with Claude Opus 5.5; any capable coding agent works.
Rehearse on mock data. The agent runs the tool on a bundle of synthetic inputs and checks each answer against the bundle's expected.json. Every check must print PASS.
Go private. Only then do you run your own data against the local API, yourself, on that machine. Never give the agent real data during setup: a coding agent that runs in the cloud sees everything in its context, so keep real data out of the chat and out of the files it reads.

Rehearsal command

docker compose exec api python scripts/rehearse.py prior-auth-check

Download the mock-data bundle (6 KB, 8 checks)expected.json

Two synthetic CPAP requests checked against the CPAP section of Aetna Clinical Policy Bulletin 0004 (Obstructive Sleep Apnea in Adults), before sending. In the first, an attended in-lab sleep study shows an AHI of 26.5 over more than 6 hours of sleep: the check must say ready to send, quote the study, and draft a letter of medical necessity. In the second, the home sleep test index is 3.6 events per hour, below the policy minimum, while a physician letter asserts the criteria are met: the check must say not supported on this chart and draft no letter. The signed record must verify, and fail once changed.

What the rehearsal checks

the supported request is ready to send
a letter of medical necessity is drafted and cites the AHI
the unsupported request is not supported on this chart
and no letter is drafted for it
the not-met criterion quotes the 3.6 index
the signed record verifies
a record whose decision was changed no longer verifies
every model call has a signed receipt

Licence: Synthetic charts (CC0): patients, notes and clinicians are invented. Policy: an excerpt of Aetna CPB 0004 (the payer's published medical policy, https://www.aetna.com/cpb/medical/data/1_99/0004.html), quoted for demonstration with its source. Part of decosa-api, AGPL-3.0-or-later.

Prompt for your coding agent