Filter documents by metadata values

Retrieve documents whose metadata contains one or more of the given values (case-insensitive, OR logic).

Document metadata is stored as a list of [key, value] pairs. This endpoint matches against the value part of each pair. For example, if a document has metadata [["category", "Finance"]], passing metadata_values: ["finance"] will match it.

Note: This endpoint requires documents to have metadata set. See the metadata management endpoints below to add metadata to documents.

POST /projects/{project_id}/documents/filter-by-metadata

Filter documents by metadata values

Python

import requests

url = "https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/documents/filter-by-metadata/"

payload = { "metadata_values": ["Finance", "Legal"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

200

{
  "count": 123,
  "next": "<string>",
  "previous": "<string>",
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "content_type": "<string>",
      "page_count": 123,
      "file_size": 123,
      "metadata": [
        [
          "<string>"
        ]
      ],
      "status": "active"
    }
  ]
}

Authorizations

BearerAuthTokenAuth

Authorization · string · header · required

Use Authorization: Bearer

Path Parameters

project_id · string<uuid> · required

UUID of the project

Query Parameters

limit · integer · default: 100

Maximum number of results per page

Required range: 1 <= x <= 1000

offset · integer · default: 0

Number of results to skip for pagination

Required range: x >= 0

Body

application/json

metadata_values · string[] · required

List of metadata values to filter by (OR logic, case-insensitive).

Response

200

application/json

Successful response

count · integer

Total number of results

next · string<uri> | null

URL to next page of results

previous · string<uri> | null

URL to previous page of results

results · object[]

Show child attributes