API Access

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

API Credits

Balance: -- credits

¢8.5 /credit

Purchase API Credits

≈ 118 pages

Minimum purchase: $10

Your API Key

Beta

Loading your API key...

Quick Start

Works with documents, images, audio & video

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 (page+coords or time+coords)
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
print(d["schema_errors"])  # any type/required mismatches

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 }

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
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}] }

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 50 MB. 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.	1 / page
Parse	`POST /parse`	Converts the whole document to clean markdown + typed layout blocks (headings/tables/…); `grounded=true` adds a box per block.	1 / page

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

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`	Same engine as Review, for an outbound/generated doc → adds a top-level `verified` true/false gate.	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

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. For Ask/Review/Compute on media, transcribe first, then pass the transcript as text.

Task	Endpoint	What it does · when to use	Cost
Transcribe	`POST /transcribe`	Audio/video → speaker-labeled transcript PDF.	3 / min
Process media	`POST /process-media`	Audio/video → `transcript_segments` + `video_intelligence` JSON (feed into Ask/Review/Compute).	3 / min

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 · 500 Processing error

Rate Limits

100

Requests per minute

Requests per day

50 MB

Max file size

Need higher limits? Contact us for custom plans.

Loading...

API Access

API 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

Rate Limits