# Search within a document

Performs a keyword search within the content of a specific document, returning a relevance-scored series of matching positions. This is distinct from the query endpoint, which searches across documents — query-within searches inside a single document's indexed content.

This is most useful for long-form content where you want to locate specific passages, pages, or moments, for example:

- Finding the page in a PDF where a keyword appears
- Locating the timestamp in a video where a term is spoken
- Searching within a large document's indexed text body

## Request Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | The ID of the document to search within |
| keywords | string | Yes | The keyword or phrase to search for within the document's content |
| minScore | number | No | Minimum relevance score threshold (0.0–1.0). Points scoring below this value are excluded from the response. Use to filter out low-confidence matches. |

## Response

| Field | Description |
|---|---|
| series | A scored series of matching positions within the document |

Each point in the series contains:

| Field | Type | Description |
|---|---|---|
| score | number | Relevance score for this match (higher is more relevant) |
| ref | integer or string | Position reference — an integer page index for paginated content (PDFs, slide decks), or a timecode string for time-based content (video, audio) |

## Example

To find all moments in a video where "product launch" is mentioned, with a minimum relevance score of 0.5:

json
{
  "id": "doc01abc123",
  "keywords": "product launch",
  "minScore": 0.5
}


The response series would contain entries like:
json
{
  "series": [
    { "score": 0.92, "ref": "00:01:34" },
    { "score": 0.71, "ref": "00:08:12" }
  ]
}


For a PDF, ref values would be zero-based page indices (0, 4, 11, etc.).

Endpoint: POST /api/v1/document/query-within
Version: 3.0
Security: bearerAuth

## Request fields (application/json):

  - `id` (string)
    Rule data fields

  - `keywords` (string)
    Rule data fields

  - `minScore` (number)

## Response 200 fields (application/json):

  - `series` (object)

  - `series.points` (array)

  - `series.points.score` (number)

  - `series.points.index` (integer)

  - `series.points.timecode` (string)
    Rule data fields

## Response 400 fields (application/json):

  - `message` (string)

## Response 401 fields (application/json):

  - `message` (string)

## Response 403 fields (application/json):

  - `message` (string)

## Response 404 fields (application/json):

  - `message` (string)

## Response 409 fields (application/json):

  - `message` (string)

## Response 429 fields (application/json):

  - `message` (string)

## Response 499 fields (application/json):

  - `message` (string)

## Response 500 fields (application/json):

  - `message` (string)

## Response 501 fields (application/json):

  - `message` (string)

## Response 503 fields (application/json):

  - `message` (string)

## Response 504 fields (application/json):

  - `message` (string)