> ## 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.

# RAG PDF Highlighter — Request and Response Schemas

> Full schema reference for the HighlightRequest and DocumentPayload request bodies, and all success and error response formats returned by the API.

This page provides a complete schema reference for every request and response shape used by the RAG PDF Highlighter API. Use it as a quick lookup when integrating the service into your pipeline or writing client code.

## HighlightRequest

The `HighlightRequest` schema defines the JSON body accepted by `POST /highlight`. Both fields are required.

```json theme={null}
{
  "pdf_url": "https://example.com/document.pdf",
  "documents": [
    {
      "page_content": "Text chunk to highlight",
      "metadata": {
        "page": 0,
        "source": "document.pdf",
        "chunk_id": "abc123"
      }
    }
  ]
}
```

<ParamField body="pdf_url" type="string" required>
  The fully qualified URL of the PDF to download and annotate. The service performs an HTTP GET against this URL at request time. The URL must be reachable from the host running the service and must return a valid PDF file with a 200 status code.
</ParamField>

<ParamField body="documents" type="array" required>
  A non-empty list of `DocumentPayload` objects. Each object represents one text chunk that the service will locate and highlight in the PDF. Passing an empty array results in a `400 Bad Request` response.

  <Expandable title="DocumentPayload properties">
    <ParamField body="page_content" type="string" required>
      The verbatim text string to search for and highlight on the target page. For best results, use the exact text as it appears in the PDF — the highlighter performs a literal string search rather than a fuzzy match.
    </ParamField>

    <ParamField body="metadata" type="object">
      An arbitrary key-value object associated with the chunk. The highlighter reads exactly one key from this object:

      * **`page`** (`integer`, 0-indexed): the page number in the PDF where the chunk appears. Page `0` is the first page. If `page` is absent, the highlighter may not be able to locate the chunk.

      All other keys you include in `metadata` are accepted, stored as-is, and ignored by the highlighting logic.
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  You can include any extra fields in `metadata` beyond `page` — for example `source`, `chunk_id`, `score`, or any other key your RAG pipeline produces. The highlighter preserves these fields in the `DocumentPayload` object and simply ignores them when processing highlights. This means you can pass your retriever's raw output directly without stripping metadata.
</Tip>

## Success Response

When highlighting succeeds, the API returns the annotated PDF as a binary stream.

| Property              | Value                                    |
| --------------------- | ---------------------------------------- |
| HTTP status           | `200 OK`                                 |
| `Content-Type`        | `application/pdf`                        |
| `Content-Disposition` | `attachment; filename="highlighted.pdf"` |
| Body                  | Raw binary PDF data                      |

Write the response body directly to a `.pdf` file. Do not attempt to parse it as JSON.

## Error Response

All error responses — `400`, `422`, and `500` — share the same outer shape: a JSON object with a single `detail` key.

```json theme={null}
{"detail": "Failed to download PDF: Connection timeout"}
```

For `422 Unprocessable Entity` errors, `detail` is an array of Pydantic validation error objects rather than a plain string:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "pdf_url"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

<ResponseField name="detail" type="string | array">
  A human-readable description of the error. For `400` and `500` errors this is a plain string. For `422` validation errors this is an array of objects, each containing:

  * **`loc`** (`array`): the location of the invalid field, e.g. `["body", "pdf_url"]`
  * **`msg`** (`string`): a description of the validation failure
  * **`type`** (`string`): a Pydantic error type identifier, e.g. `"value_error.missing"`
</ResponseField>

For a complete breakdown of each error code, its causes, and recommended fixes, see the [Errors](/api/errors) reference page.