# 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**

```typescript 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();

```

```python 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,
    ),
)

```

## Related pages

- [Credal | Documentation](../index.md)
- [Overview](./api-reference-v-0-overview.md)
- [Docs](../guides.md)
- [Introduction](./getting-started-introduction.md)
- [API Reference](./api-reference-index.md)
- [Service Accounts](./api-reference-v-0-service-accounts.md)
- [Quickstart](./getting-started-quickstart.md)
- [Overview](./api-reference-v-1-overview.md)
- [Overview](./getting-started-tutorials-common-first-agents-employee-onboarding-assistant-overview.md)
- [OAuth Setup](./api-reference-v-1-o-auth-setup.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.