Team and Finance Control plans

Invoice decisions (decision_version 2)

Plan keys can ask POST /v1/judge (and POST /v1/duplicate) for an invoice decision instead of a pass or fail verdict. Send policy_id and decision_version 2. The policy must set rules.max_amount. Accounts created on or after 2026-12-23 get version 2 by default when they send a policy_id.

Send exactly one of invoice (structured fields), invoice_text (plain text) or agent_output. task is optional and defaults to "Check this invoice against the payment policy." Without decision_version 2, invoice, invoice_text and po return 400 invalid_request.

The response has decision (approve, needs_review, deny or retry), decision_source (rules, or rules+model when a model added triage), the rules that ran, review_id when a review was opened, and the usual reasons and receipt. deny and retry come from the rules alone and are not billed. approve and needs_review are billed as one normal call. needs_review opens a review for a person.

• invoice: vendor, invoice_number, po_number, currency (3 letters), issue_date (YYYY-MM-DD), line_items (description, qty, unit_price, amount), subtotal, tax, total. Amounts are numbers or decimal strings with up to 6 decimals. At most 2,000 line items; the whole body is at most 256 KB.
• po (optional): po_number, vendor, currency, total. Checked against the invoice.

curl -s https://screwtape.ai/v1/judge \
  -H "Authorization: Bearer $SCREWTAPE_KEY" -H "Content-Type: application/json" \
  -d '{"policy_id":"ap-default","decision_version":2,
       "invoice":{"vendor":"Acme Ltd","invoice_number":"INV-1042","currency":"USD","issue_date":"2026-10-01",
                  "line_items":[{"description":"Support","qty":1,"unit_price":"1200.00","amount":"1200.00"}],
                  "subtotal":"1200.00","tax":"0","total":"1200.00"},
       "po":{"po_number":"PO-77","vendor":"Acme Ltd","currency":"USD","total":"1200.00"}}'

invoice_text: plain-text invoices

invoice_text is a string of at most 5,000 characters. The worker reads vendor, invoice number, currency, line items, subtotal, tax and total from it with fixed parsing rules. No model reads the text, and the text is not stored or signed: only its SHA-256 goes into the receipt. The response has extraction: "deterministic".

Longer text returns 413 with error.code payload_too_large and the message "invoice_text takes at most 5000 characters. Send larger invoices as structured invoice fields." For bigger invoices, send the structured invoice fields instead. They have no character limit (up to 2,000 line items and a 256 KB body) and are read exactly.

If the text does not reconcile (two different totals, line items that do not add up, or a missing vendor, currency or total), the decision is needs_review with error_type extraction_unreconciled. Text that cannot be read is never denied on that basis; a person reviews it. Text that reconciles goes through the policy like a structured invoice, so a total over max_amount is still denied.

curl -s https://screwtape.ai/v1/judge \
  -H "Authorization: Bearer $SCREWTAPE_KEY" -H "Content-Type: application/json" \
  -d '{"policy_id":"ap-default","decision_version":2,"invoice_text":"Acme Ltd\nInvoice INV-1042\nCurrency USD\nTotal 1200.00"}'

Own model key (X-Model-Key)

On a needs_review decision, a policy with model_triage set asks a model for a short explanation. A model can never loosen a decision. You can have that triage run on your own model account by sending these headers with a decision_version 2 call that has a policy_id. Without both, X-Model-Key returns 400: "X-Model-Key works only with decision_version 2 and a policy_id."

Your key is used for that one request only. It is never stored, logged, signed or returned in a response. The receipt records only the provider host and the model id.

If your provider fails, times out (15 seconds) or returns something unusable, the decision stays the rules decision, needs_review, with decision_source rules. The call does not fall back to our model. An own-key call is billed as one normal call, the same as any approve or needs_review.

Own-key headers are not available over MCP. The MCP server ignores X-Model-* headers on every tool. Use the HTTP API.

• X-Model-Key (required for this feature): 8 to 512 printable characters.
• X-Model-Provider (optional): groq (default) or openai-compatible.
• X-Model-Base-URL: required for openai-compatible, and must be one of https://api.groq.com/openai/v1, https://api.openai.com/v1, https://api.together.xyz/v1, https://api.fireworks.ai/inference/v1, https://openrouter.ai/api/v1, https://api.mistral.ai/v1, https://api.deepseek.com/v1. groq uses https://api.groq.com/openai/v1.
• X-Model-Id (optional): 1 to 120 letters, digits, . _ : / or -. groq defaults to openai/gpt-oss-120b.

curl -s https://screwtape.ai/v1/judge \
  -H "Authorization: Bearer $SCREWTAPE_KEY" -H "Content-Type: application/json" \
  -H "X-Model-Key: $YOUR_GROQ_KEY" \
  -d '{"policy_id":"ap-default","decision_version":2,"invoice":{...}}'

Evidence and replay

Turn evidence on per policy with evidence: {"enabled": true, "retain_days": 90, "store_vendor_name": false}. retain_days is 1 to 400 (default 90). Each approve or needs_review then keeps one small record: the fields the rules read, the policy version and the rule results. It keeps no line descriptions, addresses or bank details, and the vendor is a keyed hash unless store_vendor_name is true. The record's SHA-256 is signed into the receipt as evidence_sha256. deny and retry keep no evidence.

Evidence counts toward the content history quota and is included in GET /v1/retention (export) and DELETE /v1/retention (erase). When the quota is full, evidence is skipped; the decision is never blocked.

POST /v1/receipts/{receipt_id}/replay re-runs the rules on the stored record. policy is original (the policy version used at the time, the default) or current. Optional document is the original body (for example {"invoice": {...}}) to prove it is the same document. The response has original, replayed, match, diffs, model_part ("recorded, not re-run" or "no model ran"), document_match and a signed replay_receipt. A model is never called again. Replay needs a plan key and is not billed.

DELETE /v1/receipts/{receipt_id}/evidence deletes the record and returns {"deleted": true}. The signed receipt is kept.

• 400 invalid_request: bad receipt id or body.
• 404 receipt_not_found, evidence_not_found (evidence was off, or the decision was deny or retry), policy_not_found.
• 410 evidence_deleted: deleted or expired; the receipt is kept.
• 409 evidence_tampered (record does not match the signed hash), document_mismatch, rules_version_unknown.

curl -s -X POST https://screwtape.ai/v1/receipts/$RECEIPT_ID/replay \
  -H "Authorization: Bearer $SCREWTAPE_KEY" -H "Content-Type: application/json" \
  -d '{"policy":"original"}'