POST /highlight — Annotate a PDF with RAG Text Chunks

The /highlight endpoint is the core of the RAG PDF Highlighter API. You give it a publicly accessible URL to a PDF and a list of text chunks retrieved from your RAG pipeline, and it downloads the PDF, locates each chunk on its target page, applies yellow highlights, and streams the annotated file back to you as a binary PDF download.

Request

Method: POST
Path: /highlight
Content-Type: application/json

Body Parameters

string

required

A publicly accessible URL pointing to the PDF you want to annotate. The service downloads this file at request time, so the URL must be reachable from the host running the service.

array

required

A list of document chunk objects to locate and highlight in the PDF. Each element must conform to the DocumentPayload shape.

Show Document object properties

string

required

The exact text string to find and highlight on the target page. The highlighter searches for this string verbatim, so it should match the text in the PDF as closely as possible.

object

Key-value metadata associated with the chunk. The highlighter reads metadata.page to determine which page to search. All other keys are preserved but ignored during highlighting.

metadata.page (integer): The 0-indexed page number where the chunk appears. Page 0 is the first page of the document. If omitted, the highlighter may not be able to locate the chunk.

Page numbers in metadata.page are 0-indexed. The first page of your PDF is page 0, the second is page 1, and so on. If your RAG pipeline stores 1-indexed page numbers, subtract 1 before sending them to this API.

Examples

curl -X POST http://localhost:8000/highlight \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/research-paper.pdf",
    "documents": [
      {
        "page_content": "The results demonstrate a 23% improvement",
        "metadata": {"page": 4}
      },
      {
        "page_content": "We conclude that the proposed method is effective",
        "metadata": {"page": 12}
      }
    ]
  }' \
  --output highlighted.pdf

import requests

response = requests.post(
    "http://localhost:8000/highlight",
    json={
        "pdf_url": "https://example.com/research-paper.pdf",
        "documents": [
            {
                "page_content": "The results demonstrate a 23% improvement",
                "metadata": {"page": 4}
            },
            {
                "page_content": "We conclude that the proposed method is effective",
                "metadata": {"page": 12}
            }
        ]
    }
)

if response.status_code == 200:
    with open("highlighted.pdf", "wb") as f:
        f.write(response.content)

Responses

200 OK

The highlights were applied successfully. The response body is a binary PDF file.

Header	Value
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="highlighted.pdf"`

Write the raw response bytes to a .pdf file to view the result.

400 Bad Request

Returned when the request is structurally valid but the service cannot complete it. See the Errors page for specific causes including PDFDownloadError and NoDocumentsError.

{"detail": "Failed to download PDF: HTTP 404"}

422 Unprocessable Entity

Returned by Pydantic when required fields (pdf_url or documents) are missing or have the wrong type.

{
  "detail": [
    {
      "loc": ["body", "pdf_url"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error

An unexpected error occurred during processing. Check the service logs for details.

{"detail": "Highlighting failed: <error message>"}

If a chunk’s text cannot be found on its target page, the service silently skips that chunk and continues processing the remaining documents. No error is raised and the returned PDF will simply not contain a highlight for that chunk. See Chunks not highlighted for common causes.

Endpoints

Reference

POST /highlight — Annotate a PDF with RAG Text Chunks

Request

Body Parameters

Examples

Responses

200 OK

400 Bad Request

422 Unprocessable Entity

500 Internal Server Error

​Request

​Body Parameters

​Examples

​Responses

​200 OK

​400 Bad Request

​422 Unprocessable Entity

​500 Internal Server Error

Request

Body Parameters

Examples

Responses

200 OK

400 Bad Request

422 Unprocessable Entity

500 Internal Server Error