> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salmanahmad.online/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /highlight — Annotate a PDF with RAG Text Chunks

> POST /highlight accepts a PDF URL and document chunks, locates each chunk in the PDF, and returns an annotated binary PDF with highlights applied.

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

<ParamField body="pdf_url" type="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.
</ParamField>

<ParamField body="documents" type="array" required>
  A list of document chunk objects to locate and highlight in the PDF. Each element must conform to the DocumentPayload shape.

  <Expandable title="Document object properties">
    <ParamField body="page_content" type="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.
    </ParamField>

    <ParamField body="metadata" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  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.
</Warning>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## 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](/api/errors) page for specific causes including `PDFDownloadError` and `NoDocumentsError`.

```json theme={null}
{"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.

```json theme={null}
{
  "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.

```json theme={null}
{"detail": "Highlighting failed: <error message>"}
```

<Note>
  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](/api/errors#chunks-not-highlighted) for common causes.
</Note>