Search Documents

Endpoint

POST /v2/core/documents/search

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: sor:read The organization and user context are derived from your access token. You never pass an organization or user identifier in the request body.

Results are restricted to the document types the access token’s user may reach. Two users authorizing the same application can get different results for the same query.

Request Body

All fields are optional. An empty body ({}) returns the first page of documents with no filters applied.

Field	Type	Description
`limit`	integer	Maximum number of documents to return. Between `1` and `200`. Defaults to `100`
`offset`	integer	Number of documents to skip, for offset-based pagination. Must be `>= 0`. Defaults to `0`
`last_updated_at`	string or null	Cursor for incremental fetching by update time. Pass the `next_cursor` from a previous response to get the next page
`last_created_at`	string or null	Cursor for incremental fetching by creation time. Pass the `next_cursor` from a previous response to get the next page
`filters`	array	List of filter objects to narrow the results. Defaults to `[]` (no filtering). See Filter Types

Pagination modes are mutually exclusive:

You may set at most one of last_updated_at or last_created_at.
offset cannot be combined with last_updated_at or last_created_at.

Violating these rules returns a 422 error. Use offset/limit for simple paging, or a single cursor for incremental syncs.

Filter Types

Each entry in filters is one of three object types, selected by its type field.

Field Filter

Filters on a document header field or an org field.

Field	Type	Required	Description
`type`	string	Yes	Must be `"field"`
`field_id`	integer	Yes	The field to filter on. See reserved header field IDs below; any other ID is treated as an org field ID
`operator`	string	Yes	Comparison operator. See Operators
`value`	any	Yes	Value to compare against. See Values

Reserved header field IDs:

ID	Field
`1`	document type
`2`	document title
`3`	file name
`4`	uploaded by user ID
`5`	active
`6`	source
`7`	document created at
`8`	exhibits
`9`	category

Filters on a mapped attribute.

Field	Type	Required	Description
`type`	string	Yes	Must be `"attribute"`
`attribute_id`	string	Yes	Attribute identifier in the form `<name>_<type>`, e.g. `opportunity_id_text`
`operator`	string	Yes	Comparison operator. See Operators
`value`	any	Yes	Value to compare against. See Values

Group Filter

Combines nested filters with a boolean operator. Groups can be nested recursively.

Field	Type	Required	Description
`type`	string	Yes	Must be `"group"`
`group_operator`	string	No	How to combine the nested filters: `"and"` or `"or"`. Defaults to `"and"`
`filters`	array	Yes	List of nested filter objects (field, attribute, or group)

Operators

The operator field accepts one of: eq, in, gt, gte, lt, lte, not_in, between, contains, not_contains, exists.

Values

The value field is either a scalar (string, number, or boolean) or an array of scalars. Use an array for operators that expect multiple values, such as in, not_in, and between.

Request Example

curl -X POST "https://platform.chamelio.ai/v2/core/documents/search" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "filters": [
      {
        "type": "group",
        "group_operator": "and",
        "filters": [
          {
            "type": "field",
            "field_id": 1,
            "operator": "eq",
            "value": "Master Services Agreement"
          },
          {
            "type": "attribute",
            "attribute_id": "opportunity_id_text",
            "operator": "in",
            "value": ["OPP-1001", "OPP-1002"]
          }
        ]
      }
    ]
  }'

import requests

url = "https://platform.chamelio.ai/v2/core/documents/search"
headers = {
    "Authorization": "Bearer your_access_token",
    "Content-Type": "application/json"
}

payload = {
    "limit": 50,
    "filters": [
        {
            "type": "group",
            "group_operator": "and",
            "filters": [
                {
                    "type": "field",
                    "field_id": 1,
                    "operator": "eq",
                    "value": "Master Services Agreement"
                },
                {
                    "type": "attribute",
                    "attribute_id": "opportunity_id_text",
                    "operator": "in",
                    "value": ["OPP-1001", "OPP-1002"]
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const response = await fetch('https://platform.chamelio.ai/v2/core/documents/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    limit: 50,
    filters: [
      {
        type: 'group',
        group_operator: 'and',
        filters: [
          {
            type: 'field',
            field_id: 1,
            operator: 'eq',
            value: 'Master Services Agreement'
          },
          {
            type: 'attribute',
            attribute_id: 'opportunity_id_text',
            operator: 'in',
            value: ['OPP-1001', 'OPP-1002']
          }
        ]
      }
    ]
  })
});

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "documents": [
    {
      "document_id": 90210,
      "org_id": 42,
      "file_name": "acme_msa.pdf",
      "document_title": "Acme Master Services Agreement",
      "document_type": "Master Services Agreement",
      "summary": "Master services agreement between Acme and Contoso.",
      "fields": [
        {
          "field_name": "Governing Law",
          "field_value_type": "enum",
          "org_field_id": 301,
          "value": "Delaware",
          "is_unclear": false,
          "is_null": false
        }
      ],
      "workflow_metadata": {
        "workflow_state_id": "wfs_abc123xyz",
        "workflow_id": "vendor_contract_review",
        "org_id": 42,
        "user_id": 7,
        "workflow_version": 3,
        "task_id": 12345
      },
      "document_created_at": "2026-05-14T09:30:00Z",
      "mapped_fields": [
        {
          "name": "opportunity_id",
          "field_type": "text",
          "value": "OPP-1001"
        }
      ]
    }
  ],
  "has_next": true,
  "next_cursor": "2026-05-14T09:30:00Z"
}

Response Fields

Field	Type	Description
`documents`	array	List of matching documents. Each entry is a Document Object
`has_next`	boolean	Whether more documents are available beyond this page
`next_cursor`	string or null	Cursor to fetch the next page. Feed this value back as `last_updated_at` or `last_created_at` (matching the cursor you used) on the next request

Document Object

Each object in the documents array contains:

Field	Type	Description
`document_id`	integer	Unique identifier of the document
`org_id`	integer	Identifier of the organization that owns the document
`file_name`	string or null	Original file name
`document_title`	string or null	Human-readable document title
`document_type`	string	Document type name
`summary`	string or null	Generated summary of the document
`fields`	array	Extracted org field values. Each entry is a Field Value Object
`workflow_metadata`	object or null	Workflow context if the document originated from a workflow. See Workflow Metadata Object
`document_created_at`	string or null	Timestamp the document was created
`mapped_fields`	array	Mapped attribute values. Each entry is a Mapped Field Object

Field Value Object

Field	Type	Description
`field_name`	string	Name of the org field
`field_value_type`	string	Value type of the field (e.g. `text`, `enum`, `number`, `boolean`, `date`, `clause`)
`org_field_id`	integer	Identifier of the org field
`value`	string, number, boolean, or null	Extracted value; `null` when unavailable
`is_unclear`	boolean	Whether the extracted value is uncertain
`is_null`	boolean	Whether the field was explicitly resolved as empty

Workflow Metadata Object

Field	Type	Description
`workflow_state_id`	string	Internal workflow state identifier
`workflow_id`	string	Workflow identifier
`org_id`	integer	Organization identifier
`user_id`	integer	Identifier of the user who ran the workflow
`workflow_version`	integer or null	Workflow version number
`task_id`	integer or null	Task identifier associated with the document

Mapped Field Object

Field	Type	Description
`name`	string	Name of the mapped attribute
`field_type`	string	Type of the attribute. One of `text`, `number`, `boolean`, `date`, `link`
`value`	string or number	Value of the mapped attribute

Error Responses

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: sor:read"
}

422 Validation Error

Returned when the request body is invalid - either a local validation failure (such as combining offset with a cursor, or setting both cursors) or a filter that the search backend rejects. Filter errors are collected and returned together.

{
  "detail": [
    {
      "loc": ["body", "filters", 0, "operator"],
      "msg": "unsupported operator",
      "type": "value_error"
    }
  ]
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the search could not be completed due to a server error.

{
  "detail": "Failed to search documents"
}

Notes

To page through a large result set incrementally, use a single cursor: send the first request with no offset or cursor, then pass the returned next_cursor as last_updated_at (or last_created_at) on each subsequent request until has_next is false.

Use GET /v2/core/org-fields to look up the org_field_id and attribute identifiers you can reference in field and attribute filters.

Use Cases

This endpoint is useful for:

Document discovery - Find documents matching specific field or attribute criteria
Incremental sync - Keep an external system up to date by cursoring on last_updated_at
Reporting - Retrieve documents by type, status, or mapped attributes for analytics
Complex queries - Combine multiple conditions with nested and/or group filters

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Request Body

Filter Types

Field Filter

Attribute Filter

Group Filter

Operators

Values

Request Example

Response

Success Response

Response Fields

Document Object

Field Value Object

Workflow Metadata Object

Mapped Field Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Request Body

​Filter Types

​Field Filter

​Attribute Filter

​Group Filter

​Operators

​Values

​Request Example

​Response

​Success Response

​Response Fields

​Document Object

​Field Value Object

​Workflow Metadata Object

​Mapped Field Object

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Request Body

Filter Types

Field Filter

Attribute Filter

Group Filter

Operators

Values

Request Example

Response

Success Response

Response Fields

Document Object

Field Value Object

Workflow Metadata Object

Mapped Field Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases