Reducto API Reference for Coding Agents

# macOS / Linux
export REDUCTO_API_KEY="your_api_key_here"

# Windows (PowerShell)
$env:REDUCTO_API_KEY="your_api_key_here"

client := reducto.NewClient(option.WithAPIKey(os.Getenv("REDUCTO_API_KEY")))

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://example.com/doc.pdf"}'

from pathlib import Path
from reducto import Reducto

client = Reducto()  # reads REDUCTO_API_KEY from env

# --- Option A: Pass a URL directly (no upload needed) ---
parse_result = client.parse.run(input="https://example.com/document.pdf")

# --- Option B: Upload a local file first ---
upload = client.upload(file=Path("document.pdf"))
parse_result = client.parse.run(input=upload.file_id)

# --- Handle the response (important: check result.type for large docs) ---
import requests

if parse_result.result.type == "url":
    # Large documents return a URL instead of inline content
    chunks = requests.get(parse_result.result.url).json()
else:
    chunks = parse_result.result.chunks

for chunk in chunks:
    # Use dict access for URL results, attribute access for inline results
    content = chunk["content"] if isinstance(chunk, dict) else chunk.content
    print(content)

# --- Extract: pull specific fields ---
extract_result = client.extract.run(
    input=upload.file_id,
    instructions={
        "schema": {
            "type": "object",
            "properties": {
                "invoice_number": {"type": "string", "description": "The invoice number"},
                "total": {"type": "number", "description": "Total amount due"}
            }
        }
    }
)
# result is a list, access first item for single-document extraction
data = extract_result.result[0]
print(data["invoice_number"], data["total"])

# --- Split: find section boundaries ---
split_result = client.split.run(
    input=upload.file_id,
    split_description=[
        {"name": "Summary", "description": "Executive summary section"},
        {"name": "Financials", "description": "Financial statements and tables"}
    ]
)
for split in split_result.result.splits:
    print(f"{split.name}: pages {split.pages}")

# --- Classify: identify document type ---
classify_result = client.classify.run(
    input=upload.file_id,
    classification_schema=[
        {"category": "invoice", "criteria": ["billing info", "itemized charges"]},
        {"category": "contract", "criteria": ["legal terms", "signatures"]}
    ]
)
print(classify_result.result)

# --- Edit: fill a form ---
# NOTE: Edit uses "document_url" instead of "input" (unlike other endpoints)
edit_result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="Fill Name: John Doe, Date: 2024-01-15, Check 'Yes' for US Citizen"
)
print(edit_result.document_url)  # URL to download filled document

{
  "job_id": "uuid",
  "duration": 3.89,
  "result": {
    "type": "full",           // "full" (inline) or "url" (fetch from URL)
    "chunks": [
      {
        "content": "# Heading\n\nText content...",   // Markdown-formatted
        "embed": "Heading. Text content...",          // Embedding-optimized
        "blocks": [
          {
            "type": "Title",       // Title, Section Header, Text, Table, Figure, Key Value, etc.
            "content": "Heading",
            "bbox": {"left": 0.1, "top": 0.05, "width": 0.3, "height": 0.04, "page": 1},
            "confidence": "high"   // "high" or "low"
          }
        ]
      }
    ]
  },
  "usage": {"num_pages": 3, "credits": 4.0},
  "studio_link": "https://studio.reducto.ai/job/..."
}

import requests

if parse_result.result.type == "url":
    chunks = requests.get(parse_result.result.url).json()
    # chunks are plain dicts when fetched via URL
else:
    chunks = parse_result.result.chunks
    # chunks are SDK objects with attribute access

{
  "result": [
    {
      "invoice_number": "INV-2024-001",
      "total": 1250.00,
      "line_items": [{"description": "Widget", "amount": 500.00}]
    }
  ],
  "job_id": "uuid",
  "usage": {"num_fields": 4, "num_pages": 2, "credits": 10.0},
  "studio_link": "https://studio.reducto.ai/job/..."
}

{
  "result": {
    "total": {
      "value": 1250.00,
      "citations": [
        {
          "type": "Table",
          "content": "Total: $1,250.00",
          "bbox": {"left": 0.04, "top": 0.26, "width": 0.45, "height": 0.50, "page": 2},
          "confidence": "high"
        }
      ]
    }
  }
}

{
  "result": {
    "splits": [
      {"name": "Executive Summary", "pages": [1, 2]},
      {"name": "Financial Statements", "pages": [3, 4, 5, 6]},
      {"name": "Risk Factors", "pages": [7, 8, 9]}
    ]
  },
  "job_id": "uuid",
  "usage": {"num_pages": 9, "credits": 6.0}
}

{
  "document_url": "https://storage.reducto.ai/filled-form.pdf?...",
  "form_schema": [
    {
      "bbox": {"left": 0.1, "top": 0.2, "width": 0.4, "height": 0.03, "page": 1},
      "description": "Name field",
      "type": "text"
    }
  ],
  "usage": {"num_pages": 2, "credits": 8}
}

{
  "result": {
    "category": "invoice"
  },
  "job_id": "uuid",
  "duration": 1.23
}

# Submit async job
job = client.parse.run_job(input=upload.file_id)
print(job.job_id)

# Poll for results
import time
while True:
    result = client.job.get(job.job_id)
    if result.status in ("Completed", "Failed"):
        break
    time.sleep(2)