PDF index for IA agents

​

Advantages

​

When NOT to use

​

How it works internally

1. The backend downloads the PDF (1 time, no cache).
2. Makes sample of 32 distributed pages (start, middle, end) to build the font model.
3. Go through all the pages reading only the head (first 8 spans) to detect headings.
4. Detects repeated headers/footers in the top/bottom 12% of each page.
5. Returns JSON ~5-15KB with the entire map.
6. Delete the temporary and finish.

​

Usage pattern for AI agents

​

Pattern 1 - search by section

# Agent asks: "What was the revenue in Q3?"
spine = index_pdf(url)

# Search relevant section by title
target_section = next(
    s for s in spine["sections"]
    if "Revenue" in s["text"] or "Financial" in s["text"]
)
next_section = next(
    (s for s in spine["sections"] if s["page"] > target_section["page"]),
    None
)
end_page = (next_section["page"] - 1) if next_section else spine["page_count"]

# Order SOLO that section
markdown = convert(url, pages=f"{target_section['page']}-{end_page}")
# ~5-15K tokens instead of 250K

​

Pattern 2 - search by density

# Agent asks: "Are there any graphs or tables in this document?"
spine = index_pdf(url)

# Pages with very few chars are probably visual
visual_pages = [p["page"] for p in spine["pages"] if p["chars"] < 200]
if visual_pages:
    markdown = convert(url, pages=",".join(map(str, visual_pages[:5])))

​

Pattern 3 - user guided navigation

# Show the user an interactive TOC before downloading
spine = index_pdf(url)
toc = [
    {"page": s["page"], "title": s["text"], "level": s["level"]}
    for s in spine["sections"]
]
# User clicks on section -> request to /convert/from-url with that page

​

Actual comparison

​

Honest limitations

• Heuristic detection. Sections are detected by font size + numbering + bold. It’s not real semantics. It works very well with structured documents, but worse with free-form PDFs.
• Tables not detected v1. Only headings + body chars + repeated headers/footers. For tables use mode=balanced.
• pages[] truncated to 200. PDFs >200 pages expose pages_truncated: true; the agent must navigate to sections[].
• No server cache: each call re-downloads the PDF. If you are going to make many, keep content_hash on the client to reuse it via cache_key= in /convert/from-url.

​

Compatibility with other endpoints

• The spine tells you what to ask for. The actual extraction always goes through /convert/from-url (or any other conversion endpoint) with pages=.
• mode=ultra_fast + pages= = faster combination.