API Access

Integrate Roysa's traceable multimodal AI — documents, images, audio, and video — into your applications

Credits

Balance: -- credits

One balance — shared across the app and the API

Top up credits

Buy credits on the pricing page — one balance, used across the app and the API.

Your API Key

Beta

Loading your API key...

Quick Start

Works with documents, images, audio & video

Python SDK Typed errors, automatic retries, and grounding built in — every endpoint below as one method call.

pip install truetrace

from truetrace import TrueTrace

tt = TrueTrace(api_key="YOUR_API_KEY")   # or TrueTrace.from_env()

out = tt.extract("invoice.pdf", fields=[{"name": "Total"}])
print(out["extracted_features"]["Total"])            # "$12,480.00"
print(out["confidence_scores"]["Total"])             # 0.97
print(out["bounding_boxes"]["Total"]["boxes"][0])    # {page: 1, x1: .62, ...}

Endpoint: POST /extract Input: PDF, Image, Audio, Video Output: JSON — fields, confidence, bounding boxes, speakers, timestamps Cost: 1 credit / page · 3 credits / minute for audio & video

Extract structured fields from a PDF, image, audio, or video

# Works for PDF, image, audio (mp3/wav/...), and video (mp4/mov/...)
curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/extract \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F 'fields=[{"name":"Vendor"},{"name":"Invoice Number"},{"name":"Total Amount"},{"name":"Due Date"}]'

Extract structured fields from a PDF, image, audio, or video

import requests, json

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# Works for PDF, image, audio (mp3/wav/...), and video (mp4/mov/...)
fields = [
    {"name": "Vendor"}, {"name": "Invoice Number"},
    {"name": "Total Amount"}, {"name": "Due Date"},
]
with open("invoice.pdf", "rb") as f:
    r = requests.post(
        f"{BASE}/extract",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"fields": json.dumps(fields)},
    )
result = r.json()

print(result["mediaType"])           # "pdf" | "image" | "audio" | "video"
print(result["extracted_features"])  # {"Vendor": "Acme Corp", ...}
print(result["confidence_scores"])   # {"Vendor": 0.97, ...}
print(result["bounding_boxes"])      # per-field boxes snapped to the exact words
                                     # (source: "ocr_snapped"; media: time ranges)
print(result["creditsCharged"])      # int — same units the UI uses

# Media only — present when mediaType is "audio" or "video":
#   result["speakers"], result["timestamps"], result["citedSegments"],
#   result["durationSeconds"]; video also has result["objects"] and
#   result["onScreenText"].

Extract structured fields from a PDF, image, audio, or video

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

// Works for PDF, image, audio (mp3/wav/...), and video (mp4/mov/...)
async function extractFromFile(file) {
    const form = new FormData();
    form.append("file", file);
    form.append("fields", JSON.stringify([
        {name: "Vendor"}, {name: "Invoice Number"},
        {name: "Total Amount"}, {name: "Due Date"},
    ]));
    const r = await fetch(`${BASE}/extract`, {
        method: "POST",
        headers: {"X-API-Key": API_KEY},
        body: form,
    });
    const result = await r.json();

    console.log(result.mediaType);          // "pdf" | "image" | "audio" | "video"
    console.log(result.extracted_features); // {"Vendor": "Acme Corp", ...}
    console.log(result.confidence_scores);  // {"Vendor": 0.97, ...}
    console.log(result.bounding_boxes);     // per-field boxes
    console.log(result.creditsCharged);     // int — same units the UI uses

    // For audio/video: result.speakers, result.timestamps,
    // result.citedSegments, result.durationSeconds; video also has
    // result.objects and result.onScreenText.
    return result;
}

Ask a question about a document, image, audio, or video

# ── Document / Image ─────────────────────────────────────────────────────────
curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/document-ask \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "question=What is the termination clause?"

# ── Audio / Video (2-step) ────────────────────────────────────────────────────
# Step 1: get transcript
TRANSCRIPT=$(curl -s -X POST https://roysa-chatbot-781352878414.us-central1.run.app/process-media \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@meeting.mp4" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); \
    print(' '.join(s.get('text','') for s in d['transcript_segments']))")

# Step 2: ask about the transcript
curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/document-ask \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "question=What decisions were made?" \
  -F "transcript_text=${TRANSCRIPT}"

Ask a question about a document, image, audio, or video

import requests

API_KEY = "YOUR_API_KEY"
H = {"X-API-Key": API_KEY}
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# ── Document / Image ──────────────────────────────────────────────────────────
with open("contract.pdf", "rb") as f:
    r = requests.post(f"{BASE}/document-ask", headers=H,
        files={"file": f},
        data={"question": "What is the termination clause?"})

result = r.json()
print(result["answer"])
for ref in result["references"]:
    print(f"  [{ref['label']}] {ref['value']}  (page {ref['page']})")

# session_id can be reused for follow-up questions (no re-upload needed)
session_id = result["session_id"]

# ── Audio / Video (2-step) ────────────────────────────────────────────────────
# Step 1: process media
with open("meeting.mp4", "rb") as f:
    media = requests.post(f"{BASE}/process-media", headers=H,
        files={"file": f}).json()
transcript_text = " ".join(s["text"] for s in media["transcript_segments"])

# Step 2: ask about the transcript
r2 = requests.post(f"{BASE}/document-ask", headers=H,
    data={"question": "What decisions were made?",
          "transcript_text": transcript_text})
print(r2.json()["answer"])

Ask a question about a document or image

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

async function askAboutDoc(file, question) {
    const form = new FormData();
    form.append("file", file);
    form.append("question", question);
    const r = await fetch(`${BASE}/document-ask`, {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    const result = await r.json();
    console.log(result.answer);
    // Reuse result.session_id for follow-up questions — no re-upload
    return result;
}

async function followUp(sessionId, question) {
    const form = new FormData();
    form.append("session_id", sessionId);
    form.append("question", question);
    const r = await fetch(`${BASE}/document-ask`, {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    return (await r.json()).answer;
}

Transcribe audio or video → speaker-labeled PDF

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/transcribe \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.mp3" \
  --output transcript.pdf

Transcribe audio or video → speaker-labeled PDF

import requests

API_KEY = "YOUR_API_KEY"

with open("recording.mp3", "rb") as f:
    r = requests.post(
        "https://roysa-chatbot-781352878414.us-central1.run.app/transcribe",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
    )

# Returns a PDF; X-Transcript-Segments header has segment count
with open("transcript.pdf", "wb") as out:
    out.write(r.content)
print(f"Saved transcript.pdf ({r.headers.get('X-Transcript-Segments', '?')} segments)")

Transcribe audio or video → speaker-labeled PDF

const API_KEY = "YOUR_API_KEY";

async function transcribeMedia(file) {
    const form = new FormData();
    form.append("file", file);
    const r = await fetch("https://roysa-chatbot-781352878414.us-central1.run.app/transcribe", {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    const blob = await r.blob();
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url; a.download = "transcript.pdf"; a.click();
}

Translate a document or image to another language

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/translate-document \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "target_language=Spanish" \
  --output translated.pdf

Translate a document or image to another language

import requests

API_KEY = "YOUR_API_KEY"

with open("document.pdf", "rb") as f:
    r = requests.post(
        "https://roysa-chatbot-781352878414.us-central1.run.app/translate-document",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"target_language": "Spanish"},
    )

with open("translated.pdf", "wb") as out:
    out.write(r.content)
print("Saved translated.pdf")

Translate a document or image to another language

const API_KEY = "YOUR_API_KEY";

async function translateDoc(file, targetLanguage) {
    const form = new FormData();
    form.append("file", file);
    form.append("target_language", targetLanguage);
    const r = await fetch("https://roysa-chatbot-781352878414.us-central1.run.app/translate-document", {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    const blob = await r.blob();
    const a = document.createElement("a");
    a.href = URL.createObjectURL(blob);
    a.download = `translated_${targetLanguage}.pdf`; a.click();
}

Extract grounded geographic locations

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/geo \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@document.pdf"
# → { "locations": [ { "type", "value", "page", "bounding_box", "latitude", "longitude" } ] }

Extract grounded geographic locations

import requests

API_KEY = "YOUR_API_KEY"

with open("document.pdf", "rb") as f:
    r = requests.post(
        "https://roysa-chatbot-781352878414.us-central1.run.app/geo",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
    )

for loc in r.json()["locations"]:
    print(f"{loc['type']}: {loc['value']}  (page {loc['page']})")
    if loc.get("bounding_box"):
        print(f"  bbox: {loc['bounding_box']}")

Extract grounded geographic locations

const API_KEY = "YOUR_API_KEY";

async function geoExtract(file) {
    const form = new FormData();
    form.append("file", file);
    const r = await fetch("https://roysa-chatbot-781352878414.us-central1.run.app/geo", {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    const { locations } = await r.json();
    locations.forEach(loc => {
        console.log(`${loc.type}: ${loc.value} (page ${loc.page})`);
        if (loc.bounding_box) console.log("  bbox:", loc.bounding_box);
    });
    return locations;
}

Redact PII (and burn boxes into the PDF)

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/redact \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "target=names, SSNs, emails, phone numbers" \
  -F "apply=true"
# → { "redactions": [ { "type", "value", "page", "bounding_box", "reason" } ],
#     "count": N, "redacted_pdf_base64": "..." }   # base64 PDF with text removed

Redact PII (and burn boxes into the PDF)

import base64, requests

API_KEY = "YOUR_API_KEY"

with open("document.pdf", "rb") as f:
    r = requests.post(
        "https://roysa-chatbot-781352878414.us-central1.run.app/redact",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"target": "names, SSNs, emails, phone numbers", "apply": "true"},
    )

result = r.json()
print(f"{result['count']} regions redacted")
for item in result["redactions"]:
    print(f"  {item['type']}: '{item['value']}' (page {item['page']})")

# apply=true also returns the redacted PDF (text removed under each box)
if result.get("redacted_pdf_base64"):
    with open("redacted.pdf", "wb") as out:
        out.write(base64.b64decode(result["redacted_pdf_base64"]))

Redact PII (and burn boxes into the PDF)

const API_KEY = "YOUR_API_KEY";

async function redact(file) {
    const form = new FormData();
    form.append("file", file);
    form.append("target", "names, SSNs, emails, phone numbers");
    form.append("apply", "true");
    const r = await fetch("https://roysa-chatbot-781352878414.us-central1.run.app/redact", {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    const result = await r.json();
    // result.redactions → [{type, value, page, bounding_box, reason}]
    // result.redacted_pdf_base64 → redacted PDF (apply=true), text removed under each box
    return result;
}

Deterministic review against declared criteria

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/review \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@coi.pdf" \
  -F 'criteria=[
    {"name":"Not expired","field":"policy_expiration_date","operator":"after","value":"today"},
    {"name":"$1M+ coverage","field":"each_occurrence_limit","operator":"gte","value":1000000}
  ]' \
  -F "as_of=2026-06-03"
# → { "verdict":"fail", "criteria":[ {field,operator,reference_value,extracted_value,verdict,reason,source_reference} ],
#     "deterministic": true }   # same doc + same criteria → identical verdict every run

Deterministic review against declared criteria

import json, requests

API_KEY = "YOUR_API_KEY"
criteria = [
    {"name": "Not expired", "field": "policy_expiration_date", "operator": "after", "value": "today"},
    {"name": "$1M+ coverage", "field": "each_occurrence_limit", "operator": "gte", "value": 1_000_000},
]

with open("coi.pdf", "rb") as f:
    r = requests.post(
        "https://roysa-chatbot-781352878414.us-central1.run.app/review",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"criteria": json.dumps(criteria), "as_of": "2026-06-03"},
    )

result = r.json()
print("verdict:", result["verdict"])          # pass | fail (deterministic)
for c in result["criteria"]:
    print(f"  {c['name']}: {c['verdict']} — {c['reason']}")
    # c also has: field, operator, reference_value, extracted_value, source_reference

# Persist a named review once, then re-invoke at volume:
#   rid = requests.post(f"{BASE}/reviews", json={"name":"COI check","criteria":criteria}).json()["id"]
#   requests.post(f"{BASE}/review", files={"file": open("coi.pdf","rb")}, data={"review_id": rid})
# Audio/video: pass the transcript as data={"text": transcript, "criteria": ...}

Deterministic review against declared criteria

const API_KEY = "YOUR_API_KEY";
const criteria = [
    {name: "Not expired", field: "policy_expiration_date", operator: "after", value: "today"},
    {name: "$1M+ coverage", field: "each_occurrence_limit", operator: "gte", value: 1_000_000},
];

async function review(file) {
    const form = new FormData();
    form.append("file", file);
    form.append("criteria", JSON.stringify(criteria));
    form.append("as_of", "2026-06-03");
    const r = await fetch("https://roysa-chatbot-781352878414.us-central1.run.app/review", {
        method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
    });
    const result = await r.json();
    console.log("verdict:", result.verdict);  // deterministic
    result.criteria.forEach(c => console.log(`  ${c.name}: ${c.verdict} — ${c.reason}`));
    return result;
}

Extract nested objects & arrays via a JSON Schema

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/extract-schema \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@coi.pdf" \
  -F 'schema={"type":"object","properties":{"insurer":{"type":"string"},"policies":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"expiration_date":{"type":"string"}}}}}}'

Extract nested objects & arrays via a JSON Schema

import requests, json

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# Nested objects + repeating rows (arrays) described by a JSON Schema
schema = {"type": "object", "properties": {
    "insurer": {"type": "string"},
    "policies": {"type": "array", "items": {"type": "object", "properties": {
        "type": {"type": "string"}, "expiration_date": {"type": "string"}}}},
}}
with open("coi.pdf", "rb") as f:
    r = requests.post(f"{BASE}/extract-schema", headers={"X-API-Key": API_KEY},
                      files={"file": f}, data={"schema": json.dumps(schema)})
d = r.json()
print(d["data"])            # conforms to your schema (nested + arrays)
print(d["confidence"])      # same shape, per-leaf 0..1 (absent values = 0)
print(d["schema_errors"])   # any type/required mismatches
print(d["bounding_boxes"])  # leaf path -> source box, e.g.
# {"policies[1].expiration_date": {"boxes": [{"page": 1, "x1": 0.62, "y1": 0.51,
#   "x2": 0.68, "y2": 0.52}], "source": "ocr_snapped"}, ...}
# Coordinates are normalized 0-1; multiply by the rendered page size to draw.

Extract nested objects & arrays via a JSON Schema

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const schema = {type: "object", properties: {
  insurer: {type: "string"},
  policies: {type: "array", items: {type: "object", properties: {
    type: {type: "string"}, expiration_date: {type: "string"}}}},
}};
const form = new FormData();
form.append("file", file);
form.append("schema", JSON.stringify(schema));
const r = await fetch(`${BASE}/extract-schema`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { data, confidence, schema_errors, bounding_boxes }
// d.bounding_boxes is keyed by leaf path (e.g. "policies[1].expiration_date")
// with normalized page coords snapped to the exact words in the document.

Infer a reusable schema from sample documents

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/generate-schema \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@sample1.pdf" -F "files=@sample2.pdf" \
  -F "doc_type=invoice"

Infer a reusable schema from sample documents

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# Upload 1-100 samples of one doc type; get a schema you can verify once + reuse
files = [("files", open("sample1.pdf", "rb")), ("files", open("sample2.pdf", "rb"))]
r = requests.post(f"{BASE}/generate-schema", headers={"X-API-Key": API_KEY},
                  files=files, data={"doc_type": "invoice"})
d = r.json()
print(d["fields"])  # [{"name","type","description"}, ...]
print(d["schema"])  # JSON Schema -> feed straight into /extract-schema

Infer a reusable schema from sample documents

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const form = new FormData();
form.append("files", file1);
form.append("files", file2);
form.append("doc_type", "invoice");
const r = await fetch(`${BASE}/generate-schema`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { doc_type, fields, schema }

Document → markdown + typed layout blocks (grounded)

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/parse \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@report.pdf" \
  -F "grounded=true"

Document → markdown + typed layout blocks (grounded)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

with open("report.pdf", "rb") as f:
    r = requests.post(f"{BASE}/parse", headers={"X-API-Key": API_KEY},
                      files={"file": f}, data={"grounded": "true"})
d = r.json()
print(d["markdown"])                 # the whole document as markdown
print(d["page_count"], d["pages_parsed"], d["truncated"])  # >200-page PDFs are capped (truncated=true)
for b in d["blocks"]:                # heading | paragraph | table | key_value | ...
    print(b["type"], b["page"], b.get("boundingBoxes"))  # box per block when grounded

Document → markdown + typed layout blocks (grounded)

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const form = new FormData();
form.append("file", file);
form.append("grounded", "true");
const r = await fetch(`${BASE}/parse`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { markdown, blocks: [{type, page, boundingBoxes}], page_count, pages_parsed, truncated }

Identify the document type

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/classify \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@doc.pdf" \
  -F 'categories=["invoice","certificate of insurance","resume"]'

Identify the document type

import requests, json

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# categories is optional - omit to let the model infer a specific type
with open("doc.pdf", "rb") as f:
    r = requests.post(f"{BASE}/classify", headers={"X-API-Key": API_KEY},
                      files={"file": f},
                      data={"categories": json.dumps(["invoice", "certificate of insurance", "resume"])})
d = r.json()
print(d["category"], d["confidence"])  # "certificate of insurance" 0.98
print(d["alternatives"])               # other plausible types

Identify the document type

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const form = new FormData();
form.append("file", file);
form.append("categories", JSON.stringify(["invoice", "certificate of insurance", "resume"]));
const r = await fetch(`${BASE}/classify`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { category, confidence, alternatives }

Split a multi-document PDF pack into labeled segments

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/split \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@packet.pdf"

Split a multi-document PDF pack into labeled segments

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

with open("packet.pdf", "rb") as f:
    r = requests.post(f"{BASE}/split", headers={"X-API-Key": API_KEY}, files={"file": f})
d = r.json()
print(d["total_pages"])
for s in d["segments"]:   # contiguous, page-covering segments
    print(s["document_type"], s["start_page"], "-", s["end_page"], s["confidence"])

Split a multi-document PDF pack into labeled segments

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const form = new FormData();
form.append("file", file);
const r = await fetch(`${BASE}/split`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { total_pages, segments: [{start_page,end_page,document_type}] }

Gate an outbound / generated document against criteria

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@generated.pdf" \
  -F 'criteria=[{"name":"Signed","field":"signature","operator":"is_not_empty"}]'

Gate an outbound / generated document against criteria

import requests, json

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# Same deterministic engine as /review, with a top-level verified gate.
# Accepts inline criteria OR a saved review_id.
criteria = [{"name": "Signed", "field": "signature", "operator": "is_not_empty"}]
with open("generated.pdf", "rb") as f:
    r = requests.post(f"{BASE}/verify", headers={"X-API-Key": API_KEY},
                      files={"file": f}, data={"criteria": json.dumps(criteria)})
d = r.json()
print(d["verified"])   # True / False - safe to ship?
print(d["criteria"])   # per-criterion pass/fail + source box

Gate an outbound / generated document against criteria

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const criteria = [{name: "Signed", field: "signature", operator: "is_not_empty"}];
const form = new FormData();
form.append("file", file);
form.append("criteria", JSON.stringify(criteria));
const r = await fetch(`${BASE}/verify`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { verified, verdict, criteria }

Derive new values from grounded fields (with provenance)

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/compute \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@bank_statement.pdf" \
  -F 'derived_fields=[{"name":"total","operation":"sum","inputs":["txn1","txn2","txn3"]}]'

Derive new values from grounded fields (with provenance)

import requests, json

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

# operation: sum | difference | product | quotient | average | min | max | count | concat
derived = [{"name": "total", "operation": "sum", "inputs": ["txn1", "txn2", "txn3"]}]
with open("bank_statement.pdf", "rb") as f:
    r = requests.post(f"{BASE}/compute", headers={"X-API-Key": API_KEY},
                      files={"file": f}, data={"derived_fields": json.dumps(derived)})
d = r.json()
c = d["computed"][0]
print(c["value"])         # e.g. 1300.0 (a total not printed in the doc)
print(c["derived_from"])  # which grounded inputs (value+confidence+box) fed it
# A missing input -> value null + error, never a fabricated number.

Derive new values from grounded fields (with provenance)

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const derived = [{name: "total", operation: "sum", inputs: ["txn1", "txn2", "txn3"]}];
const form = new FormData();
form.append("file", file);
form.append("derived_fields", JSON.stringify(derived));
const r = await fetch(`${BASE}/compute`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { computed: [{value, derived_from}] }

Save a named review once, then reuse it by id

# 1) Save the criteria once -> review_id (JSON body)
curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/reviews \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"COI check","criteria":[{"field":"policy_expiration_date","operator":"after","value":"today"}]}'

# 2) Reuse it on any document (high volume, identical every run)
curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/review \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@coi.pdf" -F "review_id=rev_xxxxxxxx"

Save a named review once, then reuse it by id

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"
H = {"X-API-Key": API_KEY}

# 1) Persist the criteria once -> review_id
rid = requests.post(f"{BASE}/reviews", headers=H, json={
    "name": "COI check",
    "criteria": [{"field": "policy_expiration_date", "operator": "after", "value": "today"}],
}).json()["id"]

# 2) Re-invoke it across thousands of docs
with open("coi.pdf", "rb") as f:
    d = requests.post(f"{BASE}/review", headers=H,
                      files={"file": f}, data={"review_id": rid}).json()
print(d["verdict"], d["criteria"])

Save a named review once, then reuse it by id

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";
const H = {"X-API-Key": API_KEY};

// 1) Save the criteria once -> review_id
const { id } = await (await fetch(`${BASE}/reviews`, {
    method: "POST", headers: {...H, "Content-Type": "application/json"},
    body: JSON.stringify({name: "COI check",
        criteria: [{field: "policy_expiration_date", operator: "after", value: "today"}]}),
})).json();

// 2) Reuse it on any document
const form = new FormData();
form.append("file", file);
form.append("review_id", id);
const d = await (await fetch(`${BASE}/review`, {method: "POST", headers: H, body: form})).json();

Audio / video → transcript segments + video intelligence

curl -X POST https://roysa-chatbot-781352878414.us-central1.run.app/process-media \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@meeting.mp4"

Audio / video → transcript segments + video intelligence

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://roysa-chatbot-781352878414.us-central1.run.app"

with open("meeting.mp4", "rb") as f:
    r = requests.post(f"{BASE}/process-media", headers={"X-API-Key": API_KEY}, files={"file": f})
d = r.json()
segments = d["transcript_segments"]          # [{speaker, start, end, text}, ...]
print(d.get("video_intelligence"))           # scene/object/text analysis (video)

# Then feed the transcript into Ask / Review / Compute (the 2-step media path):
text = " ".join(s["text"] for s in segments)
requests.post(f"{BASE}/review", headers={"X-API-Key": API_KEY},
              data={"text": text, "criteria": "[...]"})

Audio / video → transcript segments + video intelligence

const API_KEY = "YOUR_API_KEY";
const BASE = "https://roysa-chatbot-781352878414.us-central1.run.app";

const form = new FormData();
form.append("file", file);
const r = await fetch(`${BASE}/process-media`, {
    method: "POST", headers: {"X-API-Key": API_KEY}, body: form,
});
const d = await r.json();  // { transcript_segments, video_intelligence }
// Feed d.transcript_segments text into /document-ask, /review or /compute.

Input Formats

In the table below, Docs means any document format here. Every document endpoint (extract, extract-schema, generate-schema, parse, classify, split, ask, review, verify, compute, geo, redact, translate) accepts all of them — non-PDF documents are converted to PDF automatically before grounded extraction, so behavior is identical across formats.

PDFscanned & digital

ImagesJPEG, PNG, TIFF, WEBP, GIF, BMP

Word.doc, .docx, ODT, RTF

Excel / CSV.xls, .xlsx, ODS, .csv, .tsv

PowerPoint.ppt, .pptx, ODP

Plain text.txt, .md, .json, .xml, .yaml, .html

AudioMP3, WAV, FLAC, M4A, AAC, OGG, OPUS, WMA

VideoMP4, MOV, AVI, MKV, WEBM, WMV, FLV, M4V

Max file size 30 MB per upload. Audio/Video are accepted by /extract, /transcribe, and /process-media; for Ask/Review/Compute on media, transcribe first then pass the transcript as text / transcript_text.

Endpoint Reference

1 · Extract data

Turn a document into structured data. Don't know the fields yet? Start with Generate schema. Want a few flat fields? Use Extract. Nested data or repeating rows? Use Extract (schema). Need the whole doc as markdown/blocks? Use Parse.

Task	Endpoint	What it does · when to use	Cost
Generate schema	`POST /generate-schema`	Infers the field list (a JSON Schema) from sample docs. Use first, when you don't know what fields exist — then feed it into Extract.	1 / sample
Extract	`POST /extract`	Pulls a flat list of fields you name (e.g. name, date, total) → values + confidence + bounding boxes. Also reads audio/video.	1 / page
Extract (schema)	`POST /extract-schema`	Same idea, but for nested objects & repeating rows (line items, multiple policies) described by a JSON Schema. Every extracted leaf gets its own bounding box, keyed by path (`policies[1].expiration_date`) — duplicate values snap to their own row.	1 / page
Parse	`POST /parse`	Converts the whole document to clean markdown + typed layout blocks (headings/tables/…); `grounded=true` adds a box per block. Very large PDFs (>200 pages) are capped and return `truncated:true` with `pages_parsed` & the true `page_count`.	1 / page
Re-extract	`POST /re-extract`	Re-run one field against an already-processed document — cheaper than reprocessing the whole file when a single value looks wrong.	1 / req
Vision	`POST /vision`	Raw OCR / vision pass → words + boxes, with no field schema. Use when you want the primitives rather than an answer.	1 / req

2 · Understand & route

Figure out what a document is, where it splits, or just ask it a question.

Task	Endpoint	What it does · when to use	Cost
Classify	`POST /classify`	Identifies the document type (invoice, COI, resume…) + confidence + alternatives.	1 / req
Split	`POST /split`	Finds boundaries inside a multi-document PDF pack and labels each segment.	1 / req
Ask	`POST /document-ask`	Free-form Q&A / summaries → answer + grounded references. Reuse `session_id` for follow-ups.	1 / req
Ask (streaming)	`POST /document-ask-stream`	Same as Ask, streamed token-by-token (SSE) so you can render as it generates. References arrive with the final frame.	1 / req
Compare	`POST /compare`	2–20 documents → field-by-field delta with source boxes per document. Fields are auto-discovered when you don't name them. `export_xlsx=true` returns an audit-trail spreadsheet.	1 / doc
Organize	`POST /organize`	A set of documents → a proposed folder tree, discovered from their content (no fixed taxonomy). Returns per-document assignments + the assembled tree.	1 / doc

3 · Verify deterministic

Check declared rules against grounded values — the same document + same rules always give the identical verdict. Define review saves the rules once; Review runs them on an incoming doc; Verify is the same check framed as a yes/no gate for a doc you're about to send out; Compute derives new numbers from grounded fields.

Task	Endpoint	What it does · when to use	Cost
Define review	`POST /reviews`	Saves a named set of criteria once → `review_id`. A reusable template; checks nothing by itself.	—
Review	`POST /review`	Runs the check: document + criteria (or a saved `review_id`) → pass/fail per criterion, each with the field, operator, reference, extracted value, and source box.	1 / req
Verify	`POST /verify`	Alias of `/review` with `gate=true` — same engine, same cost. Kept for callers already on it; new integrations should use `/review`.	1 / req
Compute	`POST /compute`	Derives new values from grounded fields (sum/avg/min/max…) with provenance — e.g. a total that isn't printed in the doc.	1 / req
Workflow	`POST /workflow/run`	One call: extract → assert → route. Runs a schema extraction, evaluates your assertions against the grounded values, and returns a routing decision — the glue for straight-through processing.	1 / page

4 · Transform

Hand back a modified version or a derived view of the document.

Task	Endpoint	What it does · when to use	Cost
Redact	`POST /redact`	Finds sensitive info (PII) and, with `apply=true`, blacks it out. The opposite of Extract — remove vs read.	1 / req
Translate	`POST /translate-document`	Translates the document into another language → translated PDF.	1 / page
Geo	`POST /geo`	Extracts geographic entities (addresses, parcels, coordinates) with boxes — for mapping.	1 / req

5 · Media audio & video

Speech-to-text and media analysis. Grounding for media is temporal — answers cite start_sec/end_sec, not boxes. Use /process-media → /extract-media to pull fields with timestamps. Flattening the transcript to text for Ask/Review/Compute also works, but discards the timestamps.

Task	Endpoint	What it does · when to use	Cost
Transcribe	`POST /transcribe`	Audio/video → speaker-labeled transcript as a PDF. Want JSON? Use `/process-media` — same pass, same price, machine-readable output.	3 / min
Process media	`POST /process-media`	Audio/video → `transcript_segments` + `video_intelligence` JSON (feed into Ask/Review/Compute).	3 / min
Extract from media	`POST /extract-media`	Named fields out of audio/video → values + confidence + timestamps (and object boxes for video frames). Takes the `transcript_segments` / `video_intelligence` from `/process-media`.	1 / req

6 · Forms write, not read

Every other task reads a document. These two write one — take a blank PDF form and produce a completed, flattened document. Call /detect-form first to see the field list, then /fill-form with your values.

Task	Endpoint	What it does · when to use	Cost
Detect form fields	`POST /detect-form`	Enumerates a blank form's fields → name, type and bounding box per field. Works on flat scans, not just AcroForm PDFs.	1 / req
Fill form	`POST /fill-form`	Writes your values into the form and returns the completed PDF, plus the `bounding_box` of every field it filled so you can audit placement.	2 / doc

7 · Provenance verifiable export

A tamper-evident receipt for a processed document: a SHA-256 of the file, a Merkle tree over its pages, and a hash of the extraction. Lets a third party confirm that a specific page produced a specific answer — and lets you disclose one page's proof without revealing the rest (selective disclosure). Pure cryptography: no chain, no wallet, no gas. Requires the Pro plan or above.

Task	Endpoint	What it does · when to use	Cost
Verifiable export	`POST /provenance/export`	File + extraction → `{file_hash, units_merkle_root, extraction_hash, units[{index, hash, proof}], signature}`. Store it alongside your result.	1 / doc
Verify export	`POST /provenance/verify`	Re-checks a receipt against the original file: re-hashes the file and extraction, verifies every page's Merkle proof, and validates the signature. Returns `verified` plus a per-check breakdown.	free

8 · Async long jobs & batches

Every endpoint above is synchronous and must finish inside the request. That is fine for a handful of pages, but a 300-page PDF, an hour of video, or a folder of 500 files needs to outlive the connection. Submit a batch, then poll it — the job keeps running whether or not you stay connected.

Task	Endpoint	What it does · when to use	Cost
Submit batch	`POST /batch-extract`	Queue an extraction over many files → `{job_id, status:"queued"}`. Up to 500 files per job. Billed at submit, not per poll.	2 / file
Run batch	`POST /batch-extract/{job_id}/run`	Starts the runner for a queued job. Files are processed in parallel and each file's status is written back live.	—
Poll batch	`GET /batch-extract/{job_id}`	Current state → `{status, succeeded, failed, outputFolderId}`. Poll until `status` is `completed` or `failed`; consolidated `results.json` and `results.csv` land in the output folder.	free

Grounding (boxes & timestamps): every value we read off a page ships with the place it came from. Documents ground spatially: { "page": 1, "bbox": { "x1": 0.06, "y1": 0.94, "x2": 0.21, "y2": 0.96 } } — coordinates are normalised 0.0–1.0 with the origin at the top-left, so they survive any render scale. Audio and video ground temporally instead, as { "start_sec": 16.5, "end_sec": 19.7 }; there is no box for a spoken sentence. A value we could not locate returns bbox: null with confidence: 0 — never a missing key and never a guessed rectangle. Verdict endpoints cite their reasoning the same way: /classify returns evidence[] (the exact text that decided the type) and /split returns boundary_evidence[] per segment (what shows a new document starts on that page).

Authentication: Pass your key as X-API-Key: rk_... or Authorization: Bearer rk_....

Deterministic review (the differentiator): POST /review takes declared criteria (field, operator, value) and returns a white-box, reproducible verdict — the same document + same criteria yield identical verdicts every run. Operators: equals, not_equals, gt/gte/lt/lte, before/after/on_or_before/on_or_after, contains/not_contains, in/not_in, matches, starts_with/ends_with (+ not_), between, is_empty/is_not_empty, is_true/is_false. The token today resolves to as_of for reproducible date checks. Persist a named review with POST /reviews and re-invoke it with /review?review_id=….

Computed fields: POST /compute derives values (sum, difference, product, quotient, average, min, max, count, concat) from grounded inputs and returns provenance (which inputs fed each value). A missing input yields null — never a fabricated number.

Audio/Video with Ask: Call POST /process-media first to get transcript_segments, join the text, then send it as transcript_text to POST /document-ask. For Review / Compute on audio/video, pass that same joined transcript as text / transcript_text to POST /review or POST /compute (no new media path).

Sessions: The session_id in every /document-ask response can be reused for follow-up questions on the same document — no re-upload and 1 credit per question.

Supported audio: MP3, WAV, FLAC, OGG, M4A, AAC, WMA, OPUS · Video: MP4, MOV, AVI, MKV, WEBM, WMV, FLV, M4V

Error codes: 402 Insufficient credits · 400 Bad request · 429 Rate limit exceeded (see Retry-After) · 500 Processing error

Rate Limits

1,000

Requests per day

30 MB

Max file size per upload

Requests per minute is set by your plan, not by the key:

Plan	Requests / minute	Burst
Free trial	20	20
Pay-as-you-go	60	60
Pro	120	120
Scale	300	300
Enterprise	600 (or custom)	600

The per-minute limit is a token bucket, not a fixed window. You may spend a full minute's allowance at once — which is what a parallel batch does — and the bucket then refills continuously at your plan's rate. There is no point at which you are locked out for the remainder of a minute.

Exceeding it returns 429 with an accurate Retry-After (usually a few seconds) and a body of {"error":"rate_limit_exceeded","limit":60,"burst":60,"window":"1 minute"}. The daily limit returns {"error":"daily_limit_exceeded"}. Larger audio/video files can be sent via /transcribe-upload-url → /transcribe-from-gcs. Need higher limits? Contact us for custom plans.

Loading...

API Access

Credits

Your API Key

No API Key Yet

Usage Statistics

Quick Start

Input Formats

Endpoint Reference

1 · Extract data

2 · Understand & route

3 · Verify deterministic

4 · Transform

5 · Media audio & video

6 · Forms write, not read

7 · Provenance verifiable export

8 · Async long jobs & batches

Rate Limits