API Reference

Collections

This page provides an overview of collection-related APIs.

Object Overview

Collections provide a logical grouping of source documents within the Lexi data catalog and search platform.

Endpoint, URL, and Supported Methods

Collections are managed via the Lexi server API at [http|https]://[hostname]:[port]/v1.0/tenants/[tenant-guid]/collections

Supported methods include: GET HEAD PUT DELETE

Structure

Objects have the following structure:

{
    "GUID": "default",
    "TenantGUID": "default",
    "Name": "My first collection",
    "AllowOverwrites": true,
    "AdditionalData": "Created by setup",
    "CreatedUtc": "2024-07-10T05:11:51.000000Z"
}

Properties:

  • GUID GUID globally unique identifier for the object
  • TenantGUID GUID globally unique identifier for the tenant
  • Name string name of the object
  • AllowOverwrites bool boolean specifying whether or not a source document could be overwritten
  • AdditionalData string user-supplied notes or additional data
  • CreatedUtc datetime timestamp from creation, in UTC time

Create

To create, call PUT /v1.0/tenants/[tenant-guid]/collections/[collection-guid] with the following properties using the Lexi server: Name AllowOverwrites AdditionalData 

curl -X PUT http://localhost:8601/v1.0/tenants/[tenant-guid]/collections \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [accesskey]" \
     -d '
{
    "Name": "My collection",
    "AllowOverwrites": true,
    "AdditionalData": "My notes"
}'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const createCollection = async () => {
  try {
    const response = await lexi.createCollection({
      Name: "My second collection [ASH]",
      AdditionalData: "Yet another collection",
    });
    console.log(response, "Collection created successfully");
  } catch (err) {
    console.log("Error creating Collection:", err);
  }
};

createCollection();

Read

To read a collection by GUID, call GET /v1.0/tenants/[tenant-guid]/collections/[collection-guid]. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

{
    "GUID": "oneminute",
    "TenantGUID": "default",
    "Name": "Every minute",
    "Schedule": "MinutesInterval",
    "Interval": 1,
    "CreatedUtc": "2024-07-10T05:21:00.000000Z"
}

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const retrieveCollection = async () => {
  try {
    const response = await lexi.retrieveCollection(
      "5b721b0f-2cd0-44d6-8121-9745b195fdf2"
    );
    console.log(response, "Collection fetched successfully");
  } catch (err) {
    console.log("Error fetching Collection:", err);
  }
};

retrieveCollection();

Read all

To read all collections, call GET /v1.0/tenants/[tenant-guid]/collections. This API will return a JSON array. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

[
    {
        "GUID": "00000000-0000-0000-0000-000000000000",
        "TenantGUID": "00000000-0000-0000-0000-000000000000",
        "Name": "My first collection",
        "AllowOverwrites": true,
        "AdditionalData": "Created by setup",
        "CreatedUtc": "2025-03-25T21:12:32.461527Z"
    }
]

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections' \
--header 'Authorization: ••••••'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const retrieveCollections = async () => {
  try {
    const response = await lexi.retrieveCollections();
    console.log(response, "Collection fetched successfully");
  } catch (err) {
    console.log("Error fetching Collection:", err);
  }
};

retrieveCollections();

Enumerate Collection Documents

Enumerate objects by using POST /v1.0/tenants/[tenant-guid]/collections/[guid]/documents?enumerate. The resultant object will appear as:

{
    "Success": true,
    "Timestamp": {
        "Start": "2024-10-27T06:01:17.502560Z",
        "TotalMs": 91.21,
        "Messages": {
            ... log messages ...
        }
    },
    "MaxResults": 1000,
    "IterationsRequired": 1,
    "ContinuationToken": "3135b2ba-7939-4cc3-8849-bff23b27bc9a",
    "EndOfResults": false,
    "RecordsRemaining": 46,
    "Objects": [
        {
            "GUID": "1fdbe0c8-8b85-4b0e-ac42-dd4757684a9f",
            "TenantGUID": "default",
            "BucketGUID": "example-data-bucket",
            "CollectionGUID": "default",
            "ObjectGUID": "f615ac92-d1d1-4b46-8cc5-acf721131067",
            "ObjectKey": "5.pdf",
            "ObjectVersion": "1",
            "ContentType": "application/pdf",
            "DocumentType": "Pdf",
            "SourceUrl": "http://dcc249eaaf06:8001/v1.0/tenants/default/buckets/example-data-bucket/objects/5.pdf",
            "ContentLength": 31811,
            "MD5Hash": "DC477A85FF3882BBFDEB03D7B79ECC9E",
            "SHA1Hash": "CC5D85073F193A578F97D46B8A6E4CE946270B5F",
            "SHA256Hash": "E5285C6023A46E4E8917C67CCB56B91FED2E578A7AA3129680012C029868B321",
            "CreatedUtc": "2024-10-25T14:14:22.000000Z"
        },
        { ... }
    ]
}

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000/documents?enumerate=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "MaxResults": 100,
    "Skip": 0,   
    "ContinuationToken": null, 
    "Ordering": "CreatedDescending",
    "Filters": [
        {
            "Field": "ObjectKey",
            "Condition": "IsNotNull",
            "Value": ""
        }
    ]
}'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const enumerateCollection = async () => {
  try {
    const response = await lexi.enumerateCollectionDocument(
      "00000000-0000-0000-0000-000000000000",
      {
        MaxResults: 100,
        Skip: 0,
        ContinuationToken: null,
        Ordering: "CreatedDescending",
        Filters: [
          {
            Field: "ObjectKey",
            Condition: "IsNotNull",
            Value: "",
          },
        ],
      }
    );
    console.log(response, "Collections enumerated successfully");
  } catch (err) {
    console.log("Error enumerating Collections:", err);
  }
};

enumerateCollection();

Read Top Terms

To read a collection top terms by GUID, call GET /v1.0/tenants/[tenant-guid]/collections/[collection-guid]/topterms?max-keys=10. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

{
  "yes": 152463,
  "answered": 48717,
  "apple": 20362,
  "2023": 19689,
  "compliance": 17300,
  "2022": 11238,
  "2024": 5169,
  "b2b": 2808,
  "digital": 2801,
  "products": 2800
} 

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000/topterms?max-keys=10' \
--header 'Authorization: ••••••'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const retrieveTopTerms = async () => {
  try {
    const response = await lexi.retrieveCollectionTopTerms(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "top term fetched successfully");
  } catch (err) {
    console.log("Error fetching top terms:", err);
  }
};

retrieveTopTerms();

Read Statistics

To read a collection statistics by GUID, call GET /v1.0/tenants/[tenant-guid]/collections/[collection-guid]/topterms?max-keys=10. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

{
    "Collection": {
        "GUID": "00000000-0000-0000-0000-000000000000",
        "TenantGUID": "00000000-0000-0000-0000-000000000000",
        "Name": "My first collection",
        "AllowOverwrites": true,
        "AdditionalData": "Created by setup",
        "CreatedUtc": "2025-03-25T21:12:32.461527Z"
    },
    "DocumentCount": 227,
    "TotalBytes": 197530629,
    "TermCount": 200697,
    "KeyValueCount": 8
}

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000?stats=null' \
--header 'Authorization: ••••••'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const retrieveCollectionStatistics = async () => {
  try {
    const response = await lexi.retrieveCollectionStatistics(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Statistics fetched successfully");
  } catch (err) {
    console.log("Error fetching Statistics:", err);
  }
};

retrieveCollectionStatistics();

Check existance

To check if a collection exist by GUID, call HEAD /v1.0/tenants/[tenant-guid]/collections/[collection-guid].

curl --location --head 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const collectionExists = async () => {
  try {
    const response = await lexi.collectionExists(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "collection exists");
  } catch (err) {
    console.log("Error fetching collection:", err);
  }
};

collectionExists();

Search Collection

To search for a collection, call POST /v1.0/tenants/[tenant-guid]/collections/[collection-guid]/document?search

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000/documents?search=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "MaxResults": 2,
    "Skip": 1,
    "ContinuationToken": "",
    "Ordering": "CreatedDescending",
    "Filter": {
        "CreatedAfter": "2024-01-01 00:00:00.000000",
        "CreatedBefore": "2025-01-01 00:00:00.000000",
        "Terms": [
            "foo"
        ],
        "MimeTypes": [
        ],
        "Prefixes": [
        ],
        "Suffixes": [
        ],
        "SchemaFilters": [
        ]
    }
}'


const searchCollection = async () => {
  try {
    const response = await lexi.searchCollectionDocuments(
      "00000000-0000-0000-0000-000000000000",
      {
        MaxResults: 100,
        Skip: 0,
        ContinuationToken: "",
        Ordering: "CreatedDescending",
        Filter: {
          CreatedAfter: "2025-01-01 00:00:00.000000",
          CreatedBefore: "2026-01-01 00:00:00.000000",
          Terms: ["view"],
          MimeTypes: [],
          Prefixes: [],
          Suffixes: [],
          SchemaFilters: [],
        },
      }
    );
    console.log(response, "Collections searched successfully");
  } catch (err) {
    console.log("Error searching Collections:", err);
  }
};

searchCollection()

Search collection and include data

To search for a collection with data, call POST /v1.0/tenants/[tenant-guid]/collections/[collection-guid]/document?search&incldata

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000/documents?search=null&incldata=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "MaxResults": 2,
    "Skip": 1,
    "ContinuationToken": "",
    "Ordering": "CreatedDescending",
    "Filter": {
        "CreatedAfter": "2024-01-01 00:00:00.000000",
        "CreatedBefore": "2025-01-01 00:00:00.000000",
        "Terms": [
            "foo"
        ],
        "MimeTypes": [
        ],
        "Prefixes": [
        ],
        "Suffixes": [
        ],
        "SchemaFilters": [
        ]
    }
}'

const searchCollection = async () => {
  try {
    const response = await lexi.searchCollectionDocuments(
      "00000000-0000-0000-0000-000000000000",
      {
        MaxResults: 100,
        Skip: 0,
        ContinuationToken: "",
        Ordering: "CreatedDescending",
        Filter: {
          CreatedAfter: "2025-01-01 00:00:00.000000",
          CreatedBefore: "2026-01-01 00:00:00.000000",
          Terms: ["view"],
          MimeTypes: [],
          Prefixes: [],
          Suffixes: [],
          SchemaFilters: [],
        },
      },
      true
    );
    console.log(response, "Collections searched successfully");
  } catch (err) {
    console.log("Error searching Collections:", err);
  }
};

searchCollection();

Search collection and include top terms

To search for a collection with top terms, call POST /v1.0/tenants/[tenant-guid]/collections/[collection-guid]/document?search&incltopterms

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000/documents?search=null&incltopterms=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "MaxResults": 2,
    "Skip": 1,
    "ContinuationToken": "",
    "Ordering": "CreatedDescending",
    "Filter": {
        "CreatedAfter": "2024-01-01 00:00:00.000000",
        "CreatedBefore": "2025-01-01 00:00:00.000000",
        "Terms": [
            "foo"
        ],
        "MimeTypes": [
        ],
        "Prefixes": [
        ],
        "Suffixes": [
        ],
        "SchemaFilters": [
        ]
    }
}'

const searchCollection = async () => {
  try {
    const response = await lexi.searchCollectionDocuments(
      "00000000-0000-0000-0000-000000000000",
      {
        MaxResults: 100,
        Skip: 0,
        ContinuationToken: "",
        Ordering: "CreatedDescending",
        Filter: {
          CreatedAfter: "2025-01-01 00:00:00.000000",
          CreatedBefore: "2026-01-01 00:00:00.000000",
          Terms: ["view"],
          MimeTypes: [],
          Prefixes: [],
          Suffixes: [],
          SchemaFilters: [],
        },
      },
      undefined,
      true
    );
    console.log(response, "Collections searched successfully");
  } catch (err) {
    console.log("Error searching Collections:", err);
  }
};

searchCollection();

Search collection and emit result

To search for a collection and emit result, call POST /v1.0/tenants/[tenant-guid]/collections/[collection-guid]/document?search&async

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000/documents?search=null&async=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "MaxResults": 2,
    "Skip": 1,
    "ContinuationToken": "",
    "Ordering": "CreatedDescending",
    "Filter": {
        "CreatedAfter": "2024-01-01 00:00:00.000000",
        "CreatedBefore": "2025-01-01 00:00:00.000000",
        "Terms": [
            "foo"
        ],
        "MimeTypes": [
        ],
        "Prefixes": [
        ],
        "Suffixes": [
        ],
        "SchemaFilters": [
        ]
    }
}'

const searchCollection = async () => {
  try {
    const response = await lexi.searchCollectionDocuments(
      "00000000-0000-0000-0000-000000000000",
      {
        MaxResults: 2,
        Skip: 1,
        ContinuationToken: "",
        Ordering: "CreatedDescending",
        Filter: {
          CreatedAfter: "2024-01-01 00:00:00.000000",
          CreatedBefore: "2025-01-01 00:00:00.000000",
          Terms: ["foo"],
          MimeTypes: [],
          Prefixes: [],
          Suffixes: [],
          SchemaFilters: [],
        },
      },
      undefined,
      undefined,
      true
    );
    console.log(response, "Collections searched successfully");
  } catch (err) {
    console.log("Error searching Collections:", err);
  }
};

searchCollection()

Delete

To delete a collection by GUID, call DELETE /v1.0/tenants/[tenant-guid]/collections/[collection-guid]. If the collection is not empty, a 400 will be returned.

curl --location --request DELETE 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/collections/00000000-0000-0000-0000-000000000000' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data ''

import { ViewLexiSdk } from "view-sdk";

const lexi = new ViewLexiSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const deleteCollection = async () => {
  try {
    const response = await lexi.deleteCollection(
      "1d747140-f297-4db9-9267-d30b379c2861"
    );
    console.log(response, "Collection deleted successfully");
  } catch (err) {
    console.log("Error deleting Collection:", err);
  }
};

deleteCollection();