Search Document Collection

POST https://api.credal.ai/api/v0/search/searchDocumentCollection Content-Type: application/json

Search across all documents in a document collection using the document metadata and contents.

Reference: https://docs.credal.ai/api-reference/api-reference/search/search-document-collection

Authentication

Authorization header (bearer token, required) — Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

Body (application/json)

This endpoint expects an object.

collectionId (UUID, required)
searchQuery (string, required)
userEmail (string, required) — The email of the user making the search request for permissions reduction.
structuredQueryFilters (list of SingleFieldFilter, optional) — The structured query filters to apply to the search query.
searchOptions (DocumentCollectionSearchOptions, optional)
metadataFilterExpression (string, optional, deprecated) — Legacy metadata filter expression to apply to the search query. Use structuredQueryFilters instead.

Response

200

searchTermsUsed (list of string, required)
structuredFiltersApplied (list of SingleFieldFilter, required)
searchId (UUID, required)
results (list of DocumentCollectionSearchResult, required)

Types

SingleFieldFilter

field (string, required)
operator (enum, required)
- Allowed values: <, >, <=, >=, !=, ==, contains
value (string, required)

DocumentCollectionSearchOptions

maxChunks (integer, optional) — The maximum number of chunks to return. Defaults to 10.
mergeContents (boolean, optional) — Whether to merge the chunks for a document and just return one result per document. Defaults to false.
threshold (double, optional) — The similarity threshold between 0 and 1 for the search results. A higher number leads to fewer but more relevant results. Defaults to 0.45.
enableSmartFiltering (boolean, optional) — Whether to automatically filter the search results based on the user query and available metadata on the collection. Defaults to false.
enableQueryExtraction (boolean, optional) — / Whether to extract search terms from the user query and use them for semantic search. Defaults to false.
enableReranking (boolean, optional) — Whether to rerank the search results after the initial semantic search query. Defaults to false.

DocumentCollectionSearchResult

documentId (UUID, required)
documentName (string, required)
documentUrl (string, required)
documentExternalId (string, required)
documentMetadata (map from string to string, required)
chunks (list of SearchResultChunk, required)
mergedContents (string, optional)

SearchResultChunk

chunkId (UUID, required)
chunkIndex (integer, required)
text (string, required)
score (double, required) — The similarity score between 0 and 1 for the search result. A higher number means the chunk is more relevant to the search query.

Examples

Request

JSON

{
  "collectionId": "82e4b12a-6990-45d4-8ebd-85c00e030c24",
  "searchQuery": "ABC Corp",
  "userEmail": "jack@credal.ai",
  "structuredQueryFilters": [
    {
      "field": "status",
      "operator": "==",
      "value": "Open"
    }
  ],
  "searchOptions": {
    "maxChunks": 10,
    "mergeContents": true,
    "threshold": 0.8,
    "enableSmartFiltering": true,
    "enableQueryExtraction": true,
    "enableReranking": true
  }
}

Response

JSON

{
  "searchTermsUsed": [
    "ABC Corp"
  ],
  "structuredFiltersApplied": [
    {
      "field": "status",
      "operator": "==",
      "value": "Open"
    }
  ],
  "searchId": "76b534be-5d5c-11ee-b268-87f1fd934c81",
  "results": [
    {
      "documentId": "82e4b12a-6990-45d4-8ebd-85c00e030c24",
      "documentName": "ABC Corp - Initial meeting transcript",
      "documentUrl": "https://docs.google.com/document/d/1PNiSvrRKyO4Yfv1IMnPkI1JTZr-762Rd7pRdygBi0eE/edit",
      "documentExternalId": "1PNiSvrRKyO4Yfv1IMnPkI1JTZr-762Rd7pRdygBi0eE",
      "documentMetadata": {
        "customerName": "ABC Corp",
        "meetingDate": "2021-01-01T00:00:00Z"
      },
      "chunks": [
        {
          "chunkId": "8d49fa7e-f09a-4bd4-ae94-4c089c9043a0",
          "chunkIndex": 0,
          "text": "The cat sat on the mat.",
          "score": 0.9
        },
        {
          "chunkId": "c24f99f9-2477-461b-8f8f-90a82a40879d",
          "chunkIndex": 1,
          "text": "The quick brown fox jumps over the lazy dog.",
          "score": 0.8
        },
        {
          "chunkId": "6413d18c-b37f-4985-9045-cc8d6e100a17",
          "chunkIndex": 2,
          "text": "The lazy dog lazed.",
          "score": 0.7
        }
      ],
      "mergedContents": "The cat sat on the mat. The quick brown fox jumps over the lazy dog. The lazy dog lazed."
    },
    {
      "documentId": "90998ceb-1c10-4d2a-96cb-acf89fa3005e",
      "documentName": "XYZ Corp - Follow-up transcript",
      "documentUrl": "https://credalai-my.sharepoint.com/:w:/g/credalai_onmicrosoft_com/ESb7bpzm2FdGqPTlXsQW2P4BpBhsrZuKS_PgJlaoJffo9A?e=Ecv5j1",
      "documentExternalId": "ESb7bpzm2FdGqPTlXsQW2P4BpBhsrZuKS_PgJlaoJffo9A",
      "documentMetadata": {
        "customerName": "XYZ Corp",
        "meetingDate": "2021-01-02T00:00:00Z"
      },
      "chunks": [
        {
          "chunkId": "3664912a-3edb-4d88-b624-80db99d383e6",
          "chunkIndex": 0,
          "text": "The cat sat on the mat.",
          "score": 0.7
        },
        {
          "chunkId": "da9d43a4-2927-442c-8e5c-b9ef86f56fc3",
          "chunkIndex": 1,
          "text": "The quick brown fox jumps over the lazy dog.",
          "score": 0.9
        },
        {
          "chunkId": "8d882e9f-8eda-479b-ae2a-359ebae7b626",
          "chunkIndex": 2,
          "text": "The lazy dog lazed.",
          "score": 0.75
        }
      ],
      "mergedContents": "The cat sat on the mat. The quick brown fox jumps over the lazy dog. The lazy dog lazed."
    }
  ]
}

SDK Code

searchDocumentCollectionExample

import { CredalClient } from "@credal/sdk";

async function main() {
    const client = new CredalClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.search.searchDocumentCollection({
        collectionId: "82e4b12a-6990-45d4-8ebd-85c00e030c24",
        searchQuery: "ABC Corp",
        userEmail: "jack@credal.ai",
        structuredQueryFilters: [
            {
                field: "status",
                operator: "==",
                value: "Open",
            },
        ],
        searchOptions: {
            maxChunks: 10,
            mergeContents: true,
            threshold: 0.8,
            enableSmartFiltering: true,
            enableQueryExtraction: true,
            enableReranking: true,
        },
    });
}
main();

searchDocumentCollectionExample

from credal import CredalV0
import uuid
from credal.search import SingleFieldFilter, DocumentCollectionSearchOptions

client = CredalV0(
    api_key="YOUR_TOKEN_HERE",
)

client.search.search_document_collection(
    collection_id=uuid.UUID("82e4b12a-6990-45d4-8ebd-85c00e030c24"),
    search_query="ABC Corp",
    user_email="jack@credal.ai",
    structured_query_filters=[
        SingleFieldFilter(
            field="status",
            operator="==",
            value="Open",
        )
    ],
    search_options=DocumentCollectionSearchOptions(
        max_chunks=10,
        merge_contents=True,
        threshold=0.8,
        enable_smart_filtering=True,
        enable_query_extraction=True,
        enable_reranking=True,
    ),
)