---
title: "documents.search"
method: POST
path: "/capabilities/documents.search"
tags: ["Capabilities"]
---

# documents.search

`POST /capabilities/documents.search`

Search, filter, and retrieve user's documents. Supports text search, filtering by document type, export status, date ranges, sorting, and semantic similarity. Use documents.count for totals or grouped summaries across all matching documents.

## Request body

- object
  - `query` string — Text query (used only when useSearch=true). Omit in filter-only mode.
  - `limit` number — Max documents to return
  - `sortBy` string — Sort field (docDate, amount, merchant, ...)
  - `sortOrder` number — Sort order: 1 asc, -1 desc
  - `where` object — Typed filter clause. Allowed fields: id, amount, docDate, merchant, category, docType, invoiceId, receiptId, preferredCurrency, currency, paymentStatus, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, taxAmount, subtotal, isRecurring, recurringType, entityId. Allowed ops: eq, ne, gt, gte, lt, lte, in, nin, regex, exists. Regex filters are already case-insensitive, so pass plain values like "grab" instead of inline flags like "(?i)grab".
    - `logic` 'and' | 'or'
    - `conditions` object[], required
      - `field` 'id' | 'amount' | 'docDate' | 'merchant' | 'category' | 'docType' | 'invoiceId' | 'receiptId' | 'preferredCurrency' | 'currency' | 'paymentStatus' | 'paymentMethod' | 'paymentMethodEnding' | 'fromEmail' | 'toEmail' | 'summary' | 'expenseLocation.primary.countryCode' | 'expenseLocation.primary.country' | 'expenseLocation.primary.city' | 'expenseLocation.primary.stateOrProvince' | 'expenseLocation.primary.kind' | 'taxAmount' | 'subtotal' | 'isRecurring' | 'recurringType' | 'entityId', required
      - `op` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'regex' | 'exists', required
      - `value` unknown
  - `useSearch` boolean — Enable semantic/text search
  - `searchType` 'similarity' | 'mmr' — Search mode when useSearch=true: similarity (exact-ish) or mmr (broader)
  - `exportStatus` 'all' | 'exported' | 'not-exported' — Export status filter
  - `archived` 'exclude' | 'only' | 'include' — Archive filter: exclude (default, active docs), only (archived docs), include (both).
  - `outputMode` 'compact' | 'complete' — Response shape: compact (default) or complete
  - `requiredFields` string[] — Always include these extra fields (in addition to outputMode defaults). Allowed fields: id, merchant, amount, currency, preferredCurrency, conversionRate, date, docDate, receivedAt, category, docType, summary, expenseLocation, invoiceId, receiptId, paymentStatus, entityId, entityName, exportStatus, link.

## Response `200`

Successful response

- object
  - `success` boolean
  - `code` integer
  - `data` object
    - `result` object — Capability-specific result

## Other responses

- `400` — Invalid input
- `401` — Authentication required
- `404` — Resource not found

---

[API](https://skmtc.net/receiptor/apis/receiptor-ai-api.md) · [All operations](https://skmtc.net/receiptor/apis/receiptor-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/receiptor/receiptor-ai-api/versions/da17f0eb65a2/schema)