Skip to main content

Filter Documents

Filter documents by field value conditions using composable operators including equality, comparison, range, containment, and emptiness checks.

Filter documents by composing conditions on extracted field values. Each condition targets a specific field and applies an operator to test its value. Multiple conditions are AND-combined. The endpoint also supports free-text search across document content and sorting by any field.

Field names in conditions must be valid field registry IDs (e.g. fld_a1b2c3d4). Use the field autocomplete endpoint to discover available field IDs for your workspace.
POST/v1/documents/filter

Response

Response fields

dataarrayArray of matching document objects.
data[].idstringDocument UUID.
data[].namestringOriginal filename of the document.
data[].sourceIdstringSource connection ID the document belongs to.
data[].uploadedAtstringISO 8601 ingestion timestamp.
data[].fieldValuesobjectKey-value map of extracted field values for this document.
totalintegerTotal number of documents matching all conditions.
links.selfstringLink to this endpoint.

Response

{
  "data": [
    {
      "id": "doc_x9y8z7w6",
      "name": "Invoice-2024-001.pdf",
      "sourceId": "src_m1n2o3p4",
      "uploadedAt": "2024-09-14T10:32:00Z",
      "fieldValues": {
        "supplier_name": "Acme Corp",
        "invoice_date": "2024-06-15"
      }
    }
  ],
  "total": 47,
  "links": {
    "self": "/v1/documents/filter"
  }
}

Errors

Error responses

400validation_errorA field name in conditions or sort could not be resolved to a registry field.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Build conditions programmatically by first calling GET /fields/autocomplete to resolve field IDs, then GET /fields/:fieldId/values to populate value pickers. The response includes the full fieldValues map per document, so you can render result tables without additional per-document fetches.

Related

Field Autocomplete
Omnisearch