API Reference

Embeddings Rules

This page covers configuration and management of View embeddings rule objects.

Object Overview

Embeddings rules define how embeddings are generated and where resultant data is stored within View.

Endpoint, URL, and Supported Methods

Objects are managed via the configuration server API at [http|https]://[hostname]:[port]/v1.0/tenants/[tenant-guid]/embeddingsrules

Supported methods include: GET HEAD PUT DELETE

Structure

Objects have the following structure:

{
    "GUID": "embeddings-rule",
    "TenantGUID": "default",
    "BucketGUID": "example-data-bucket",
    "OwnerGUID": "default",
    "Name": "My embeddings rule",
    "ContentType": "*",
    "GraphRepositoryGUID": "example-graph-repository",
    "VectorRepositoryGUID": "example-vector-repository",
    "ProcessingEndpoint": "http://nginx-processor:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/processing",
    "ProcessingAccessKey": "***ault",
    "EmbeddingsServerUrl": "http://nginx-embeddings:8000/",
    "EmbeddingsServerApiKey": "***ault",
    "EmbeddingsGenerator": "LCProxy",
    "EmbeddingsGeneratorUrl": "http://nginx-lcproxy:8000/",
    "EmbeddingsGeneratorApiKey": "***ault",
    "BatchSize": 16,
    "MaxGeneratorTasks": 16,
    "MaxRetries": 3,
    "MaxFailures": 3,
    "VectorStoreUrl": "http://nginx-vector:8311/",
    "VectorStoreAccessKey": "***ault",
    "MaxContentLength": 16777216,
    "CreatedUtc": "2024-07-10T05:09:32.000000Z"
}

Properties:

  • GUID GUID globally unique identifier for the object
  • TenantGUID GUID globally unique identifier for the tenant
  • BucketGUID GUID GUID of the bucket to which this embeddings rule should be associated
  • OwnerGUID GUID GUID of the user to which this rule should be attributed
  • Name string name of the rule
  • ContentType string content-type on which this rule should match
  • GraphRepositoryGUID GUID the GUID of the graph repository to which embeddings should be emitted
  • VectorRepositoryGUID GUID the GUID of the vector repository to which embeddings should be emitted
  • ProcessingEndpoint string the endpoint URL of the processing endpoint
  • ProcessingAccessKey string the access key to processing endpoint
  • EmbeddingsServerUrl string the endpoint URL of the embedding endpoint
  • EmbeddingsServerApiKey string the access key to embedding endpoint
  • EmbeddingsGenerator enum the embeddings generator to use (currently only LCProxy
  • EmbeddingsGeneratorUrl string the URL of the embeddings generator
  • EmbeddingsGeneratorApiKey string the HuggingFace API key used to interact with models on HuggingFace
  • BatchSize int maximum number of chunks to process per batch
  • MaxGeneratorTasks int maximum number of parallel tasks to invoke for embeddings generation
  • MaxRetries int maximum number of times to attempt embeddings generation against a given batch before failing
  • MaxFailure int maximum number of failures to accept before declaring that a job has failed
  • VectorStoreUrl string URL to vector server where embeddings should be stored
  • VectorStoreAccessKey string the access key to Vector store url endpoint
  • MaxContentLength int maximum content length of data to process
  • CreatedUtc datetime timestamp from creation, in UTC time

Create

To create, call PUT /v1.0/tenants/[tenant-guid]/embeddingsrules with the following properties using the configuration server: BucketGUID OwnerGUID Name ContentType TargetBucketGUID EmbeddingsGenerator GeneratorUrl GeneratorApiKey VectorRepositoryGUID

curl --location --request PUT 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddingsrules' \
--header 'content-type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "BucketGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Embeddings rule",
    "ContentType": "*",
    "GraphRepositoryGUID": "00000000-0000-0000-0000-000000000000",
    "VectorRepositoryGUID": "00000000-0000-0000-0000-000000000000",
    "ProcessingEndpoint": "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/processing",
    "ProcessingAccessKey": "default",
    "EmbeddingsGenerator": "LCProxy",
    "EmbeddingsGeneratorUrl": "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddings",
    "EmbeddingsGeneratorApiKey": "",
    "BatchSize": 512,
    "MaxGeneratorTasks": 32,
    "MaxRetries": 3,
    "MaxFailures": 3,
    "VectorStoreUrl": "http://localhost:8000/",
    "VectorStoreAccessKey": "default",
    "MaxContentLength": 16777216
}'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const createEmbeddingRules = async () => {
  try {
    const response = await api.createEmbeddingsRule({
      BucketGUID: "00000000-0000-0000-0000-000000000000",
      Name: "Embeddings rule test ash",
      ContentType: "*",
      GraphRepositoryGUID: "00000000-0000-0000-0000-000000000000",
      VectorRepositoryGUID: "00000000-0000-0000-0000-000000000000",
      ProcessingEndpoint:
        "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/processing",
      ProcessingAccessKey: "default",
      EmbeddingsGenerator: "LCProxy",
      EmbeddingsGeneratorUrl:
        "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddings",
      EmbeddingsGeneratorApiKey: "",
      BatchSize: 512,
      MaxGeneratorTasks: 32,
      MaxRetries: 3,
      MaxFailures: 3,
      VectorStoreUrl: "http://localhost:8000/",
      VectorStoreAccessKey: "default",
      MaxContentLength: 16777216,
    });
    console.log(response, "Embedding rule created successfully");
  } catch (err) {
    console.log("Error creating Embedding rule:", err);
  }
};

createEmbeddingRules();

Enumerate

Refer to the Enumeration page in REST API for details about the use of enumeration APIs.

Enumerate objects by using GET /v2.0/tenants/[tenant-guid]/embeddingsrules. The resultant object will appear as:

{
    "Success": true,
    "Timestamp": {
        "Start": "2024-10-21T02:36:37.677751Z",
        "TotalMs": 23.58,
        "Messages": {}
    },
    "MaxResults": 10,
    "IterationsRequired": 1,
    "EndOfResults": true,
    "RecordsRemaining": 16,
    "Objects": [
        {
            "GUID": "example-embeddingsrule",
            ... embeddingsrule details ...
        },
        { ... }
    ],
    "ContinuationToken": "[continuation-token]"
}

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

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);


const enumerateEmbeddingRules = async () => {
  try {
    const response = await api.enumerateEmbeddingsRules();
    console.log(response, "Embedding rules fetched successfully");
  } catch (err) {
    console.log("Error fetching Embedding rules:", err);
  }
};

enumerateEmbeddingRules();

Read

To read an object by GUID, call GET /v1.0/tenants/[tenant-guid]/embeddingsrule/[embeddingsrule-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": "59f7c18d-7342-4aef-9308-86083459dd81",
    "TenantGUID": "default",
    "BucketGUID": "example-data-bucket",
    "OwnerGUID": "default",
    "Name": "Embeddings rule",
    "ContentType": "*",
    "TargetBucketGUID": "example-embeddings-bucket",
    "VectorRepositoryGUID": "example-vector-repository",
    "DataFlowEndpoint": "http://localhost:8501/processor",
    "EmbeddingsGenerator": "LCProxy",
    "GeneratorUrl": "http://localhost:8301/",
    "GeneratorApiKey": "[huggingface API key]",
    "BatchSize": 16,
    "MaxGeneratorTasks": 16,
    "MaxRetries": 3,
    "MaxFailures": 3,
    "VectorStoreUrl": "http://localhost:8311/",
    "MaxContentLength": 16777216,
    "CreatedUtc": "2024-10-21T15:19:09.000000Z"
}

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


import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const readEmbeddingRule = async () => {
  try {
    const response = await api.retrieveEmbeddingsRule(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Embedding rule fetched successfully");
  } catch (err) {
    console.log("Error fetching Embedding rule:", err);
  }
};

readEmbeddingRule();

Note: the HEAD method can be used as an alternative to get to simply check the existence of the object. HEAD requests return either a 200/OK in the event the object exists, or a 404/Not Found if not. No response body is returned with a HEAD request.

Read all

To read all objects, call GET /v1.0/tenants/[tenant-guid]/embeddingsrules/. If the object exists, it will be returned as an array of JSON object in the response body

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

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const readAllEmbeddingRules = async () => {
  try {
    const response = await api.retrieveEmbeddingsRules();
    console.log(response, "All embedding rules fetched successfully");
  } catch (err) {
    console.log("Error fetching Embedding rules:", err);
  }
};
readAllEmbeddingRules();

Update

To update an object by GUID, call PUT /v1.0/tenants/[tenant-guid]/embeddingsrule/[embeddingsrule-guid] with a fully populated object in the request body. The updated object will be returned to you.

Note: certain fields cannot be modified and will be preserved across updates.

Request body:

{
    "BucketGUID": "example-data-bucket",
    "OwnerGUID": "default",
    "Name": "My updated embeddings rule",
    "ContentType": "*",
    "TargetBucketGUID": "example-embeddings-bucket",
    "VectorRepositoryGUID": "example-vector-repository",
    "DataFlowEndpoint": "http://localhost:8501/processor",
    "EmbeddingsGenerator": "LCProxy",
    "GeneratorUrl": "http://localhost:8301/",
    "GeneratorApiKey": "[huggingface API key]",
    "BatchSize": 16,
    "MaxGeneratorTasks": 16,
    "MaxRetries": 3,
    "MaxFailures": 3,
    "VectorStoreUrl": "http://localhost:8311/",
    "MaxContentLength": 16777216
}

curl --location --request PUT 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddingsrules/00000000-0000-0000-0000-000000000000' \
--header 'content-type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "BucketGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "An updated embeddings rule",
    "ContentType": "*",
    "GraphRepositoryGUID": "00000000-0000-0000-0000-000000000000",
    "VectorRepositoryGUID": "00000000-0000-0000-0000-000000000000",
    "ProcessingEndpoint": "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/processing",
    "ProcessingAccessKey": "default",
    "EmbeddingsGenerator": "LCProxy",
    "EmbeddingsGeneratorUrl": "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddings",
    "EmbeddingsGeneratorApiKey": "",
    "BatchSize": 512,
    "MaxGeneratorTasks": 32,
    "MaxRetries": 3,
    "MaxFailures": 3,
    "VectorStoreUrl": "http://localhost:8000/",
    "VectorStoreAccessKey": "default",
    "MaxContentLength": 16777216
}'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const updateEmbeddingRule = async () => {
  try {
    const response = await api.updateEmbeddingsRule({
      GUID: "962dfbd8-a6bf-43bb-9430-3c2a12e0b1a8",
      TenantGUID: "00000000-0000-0000-0000-000000000000",
      BucketGUID: "00000000-0000-0000-0000-000000000000",
      OwnerGUID: "00000000-0000-0000-0000-000000000000",
      Name: "Embeddings rule test updated",
      ContentType: "*",
      GraphRepositoryGUID: "00000000-0000-0000-0000-000000000000",
      VectorRepositoryGUID: "00000000-0000-0000-0000-000000000000",
      ProcessingEndpoint:
        "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/processing",
      ProcessingAccessKey: "***ault",
      EmbeddingsServerUrl:
        "http://nginx-processor:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddings",
      EmbeddingsServerApiKey: "***ault",
      EmbeddingsGenerator: "LCProxy",
      EmbeddingsGeneratorUrl:
        "http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/embeddings",
      EmbeddingsGeneratorApiKey: "",
      BatchSize: 512,
      MaxGeneratorTasks: 32,
      MaxRetries: 3,
      MaxFailures: 3,
      VectorStoreUrl: "http://localhost:8000/",
      VectorStoreAccessKey: "***ault",
      MaxContentLength: 16777216,
      CreatedUtc: "2025-03-26T09:37:15.386Z",
    });
    console.log(response, "Embedding rule updated successfully");
  } catch (err) {
    console.log("Error updating Embedding rule:", err);
  }
};

updateEmbeddingRule();

Response body:

{
    "GUID": "59f7c18d-7342-4aef-9308-86083459dd81",
    "TenantGUID": "default",
    "BucketGUID": "example-data-bucket",
    "OwnerGUID": "default",
    "Name": "My updated embeddings rule",
    "ContentType": "*",
    "TargetBucketGUID": "example-embeddings-bucket",
    "VectorRepositoryGUID": "example-vector-repository",
    "DataFlowEndpoint": "http://localhost:8501/processor",
    "EmbeddingsGenerator": "LCProxy",
    "GeneratorUrl": "http://localhost:8301/",
    "GeneratorApiKey": "[huggingface API key]",
    "BatchSize": 16,
    "MaxGeneratorTasks": 16,
    "MaxRetries": 3,
    "MaxFailures": 3,
    "VectorStoreUrl": "http://localhost:8311/",
    "MaxContentLength": 16777216,
    "CreatedUtc": "2024-10-21T15:19:09.000000Z"
}

Delete

To delete an object by GUID, call DELETE /v1.0/tenants/[tenant-guid]/embeddingsrule/[embeddingsrule-guid].

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

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const deleteEmbeddingRule = async () => {
  try {
    const response = await api.deleteEmbeddingsRule(
      "962dfbd8-a6bf-43bb-9430-3c2a12e0b1a8"
    );
    console.log(response, "Embedding rule deleted successfully");
  } catch (err) {
    console.log("Error deleting Embedding rule:", err);
  }
};

deleteEmbeddingRule();

Check existence

To check existence of an object by GUID, call HEAD /v1.0/tenants/[tenant-id]/embeddingsrules/[embeddingsrule-guid]

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

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

const embeddingRuleExists = async () => {
  try {
    const response = await api.existsEmbeddingsRule(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Embedding rule exists");
  } catch (err) {
    console.log("Error checking Embedding rule:", err);
  }
};

embeddingRuleExists();