---
title: "Find a document by what it says"
method: GET
path: "/api/v1/documents/search"
tags: ["Files"]
---

# Find a document by what it says

`GET /api/v1/documents/search`

## Request

- Base URL: `http://localhost:5180`
- URL: `http://localhost:5180/api/v1/documents/search`
- Auth: API key in cookie `better-auth.session_token`

Searches the text of the files this account has filed and of the mail its connected mailboxes received, and answers with the documents and the messages rather than with prose: each match carries the passage it was found in and where to go to see it, so every hit is checkable against the source itself.

Only ever this account’s own folder, which holds both. A search is narrowed to the account’s own folder in the index and every passage that comes back is checked against the same folder again here, so a document belonging to another portfolio cannot be reached whatever the index returns.

A document the account has since deleted is never returned, even while the index still holds it. Where nothing is indexed at all, `trouble` says so: an empty `matches` on its own does not mean the filing has nothing in it.

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

What the filing says, best first.

- object
  - `ok` unknown, required
  - `data` object, required
    - `query` string, required: The search as it was understood.
    - `matches` object[], required: One entry per document, best first. Several passages of the same document count once.
      - `documentId` string, required: Stable record id, e.g. `lse_012`.
      - `name` string, required: What the document is called on the account, not what the file was named.
      - `kind` string, required: The filing kind, e.g. `lease`.
      - `kindLabel` string, required: That kind in the words a screen shows.
      - `score` number, required: How well the best passage matched, 0 to 1. What the list is sorted by.
      - `passage` string, required: What the document says where it matched. Quoted, never summarised.
      - `filedUnder` string, nullable, required: The record it hangs off, named the way the owner names it.
      - `link` string, nullable, required: Where in the product to go to see it. Null where it hangs off nothing.
      - `createdAt` string, required: ISO 8601 timestamp.
    - `mail` object[], required: Messages from the team’s connected mailboxes, best first, searched with its documents and held to the same folder.
      - `uid` string, required: The provider’s own id for the message.
      - `mailbox` string, required: The connected address it arrived at.
      - `from` string, required: Who sent it, as the message names them.
      - `subject` string, required
      - `receivedAt` string, required: ISO 8601 timestamp.
      - `score` number, required: How well the best passage matched, 0 to 1.
      - `passage` string, required: What the message says where it matched. Quoted, never summarised.
      - `link` string, nullable, required: The conversation it was filed as. Null until it has been filed.
    - `trouble` 'unavailable' | 'failed': Absent when the index answered, whether or not it found anything. `unavailable` means no index is bound; `failed` means it refused the call or is still building.
  - `meta` object, required
    - `requestId` string, required: Echoed in the x-request-id header. Quote it in a bug report.

## Other responses

- `400`: `q` was empty or over 500 characters, or `limit` was not a whole number in range.
- `429`: Searching faster than the index answers.

---

[API](https://skmtc.dev/dardaris/apis/dardaris-api.md) · [All operations](https://skmtc.dev/dardaris/apis/dardaris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dardaris/apis/dardaris-api/revisions/4aff33835c73?raw)