Node SDK

Visit the GitHub Repo

You’ll need to Create an API Key to Authentication with Metal.

Installation

npm install @getmetal/metal-sdk
# or
yarn add @getmetal/metal-sdk

Retrieval

You’ll need to Create an API Key to Authenticate with Metal.

App Setup

Param	Type	Description
`apiKey`	string	The API Key for your Org. Learn more.
`clientId`	string	The Client ID for your Org. Learn more.
`indexId`	string	The ID of the index you want to connect with. Learn more.

import { Metal } from "@getmetal/metal-sdk";
const metal = new Metal("pk_123", "ci_123", "index-id");

`addApp()`

Parameters

Param	Type	Description
`name`	string	Name of the app.

const app = await metal.addApp({
    name: "My App",
    indexes: ["index-id"]
});

`getApp()`

Parameters

Param	Type	Description
`appId`	string	Identifier for the app.

const app = await metal.getApp("app-id");

`getApps()`

const apps = await metal.getApps();

`updateApp()`

Parameters

Param	Type	Description
`appId`	string	The unique identifier of the app you want to update.
`name`	string (optional)	The updated name for the App.
`indexes`	array (optional)	An updated array of the index connected to the app.

const app = await metal.updateApp("app-id", { name: "updated name", indexes: ["index-id"] });

`addIndex()`

Parameters

Param	Type	Description
`model`	string	Identifier for the model being used, e.g., “text-embedding-ada-002”.
`name`	string	Name of the index.
`datasource`	string	Unique identifier for the Datasource.
`indexType`	string	Type of index structure, e.g., “FLAT”, “HNSW”.
`dimensions`	number	Number of dimensions for the index. e.g.1536
`filters`	array	An array of filters specifying fields for advanced searching.

Filters

Param	Type	Description
`field`	string	Name of the attribute you wish to filter by.
`type`	string	Type of the attribute (e.g., “string”, “number”).

const payload = {
    model: "text-embedding-ada-002",
    name: "my index",
    datasource: "<datasource_id>",
    indexType: "FLAT",
    dimensions: 1536,
    filters: [
        {
            field: "name",
            type: "string"
        },
        {
            field: "age",
            type: "number"
        }
    ]
};

const newIndex = await metal.addIndex(payload);

`getIndex()`

Parameters

Param	Type	Description
`indexId`	string	Identifier for the index.

const index = await metal.getIndex("index-id");

`index()`

Add a single embedding to an index. When invoked, we will generate an embedding with one of the below embedding params and store it into a vector db.

You can only pass one of the following fields: text, imageUrl, or embedding. We only embed one field in a single request.

const textEmbedding = await metal.index({ text: "Rocket" });
// or
const imgEmbedding = await metal.index({ imageUrl: "https://path-to.img" });
// or
const rawEmbedding = await metal.index({ embedding: [0.1, 0.2, 0.3] });

You can also pass an optional id and metadata object to be stored with the embedding. Eg.

const opts = {
  id: "rocket1",
  metadata: {
    category: "space",
    another: "field",
  },
};

const embedding = await metal.index({
  text: "Rocket",
  ...opts,
});

Parameters

Param	Type	Description
Embed - `embedding`	number[]	Raw embedding to be indexed.
Embed - `imageUrl`	string	A URL for an image to be embedded and indexed.
Embed - `text`	string	The text to be embedded and indexed.
`id`	string	Optional. Identifier for your embedding.
`metadata`	object	Optional. A flexible metdata object to be stored w/ the embedding.

`indexMany()`

Bulk add multiple embedding documents to an index. When invoked, we will generate an embedding with one of the below “Embed” params and store it in a vector index.

You can only pass one of the following fields: text, imageUrl, or embedding. We only embed one field in a single request.

Parameters

Param	Type	Description
`index`	string	Required. Index id.
`embedding`	number[]	Raw embeddings to be indexed.
`imageUrl`	string	A URL for an image to be vectorized and indexed.
`text`	string	The text to be vectorized and indexed.
`id`	string	Optional. identifier for your embedding.
`metadata`	object	Optional. A flexible metdata object to be stored w/ the embedding.

await metal.indexMany([
  { text: "Megadeth", index: "index-id" },
  { text: "Metallica", index: "index-id" },
]);

`search()`

Parameters

Param	Type	Description
`embedding`	number[]	Raw embeddings to be searched.
`imageUrl`	string	A URL for an image to be vectorized and searched.
`text`	string	The text to be vectorized and searched.
`filters`	Filter	Filters included for filtered search.
`indexId`	string	Optional index id where record will get indexed.
`idsOnly`	boolean	Return only the ids of the documents.
`limit`	number	Number of documents returned by the API

Filter Object

Param	Type	Description
`and`	FilterItem[]	And clause, all members have to be satisfied.
`or`	FilterItem[]	Or clause, at least one member has to be satisfied.

Filter Item

Param	Type	Description
`field`	string	Name of the field to filter
`value`	string \| number	Value to match the filter
`operator`	string	One of: `eq`, `gt`, `gte`, `lt`, `lte`.

const results = await metal.search({
  text: "term-to-search",
  filters: { and: [{ field: "favoriteNumber", value: 666, operator:"lt"}] },
  indexId: "indexId",
  idsOnly: false,
  limit: 100,
});

`getOne()`

Retrieve a single embedding document.

Parameters

Param	Type	Description
`id`	string	The ID of the document to retrieve.
`indexId`	string	Optional. index id where record will get indexed.

const document = await metal.getOne("documentId-123");

`getMany()`

Parameters

Name	Type	Description
`ids`	Array of str	An array of document IDs to retrieve.
`indexId`	str, optional	The ID of the index from which to retrieve documents. If not provided, the default index ID will be used.

const documentIDs = ['document_id_123', 'document_id_456'];
const result = await Metal.getMany(documentIDs);

`getQueries()`

Parameters

Name	Type	Description
`indexId`	str	The ID of the index from which to retrieve documents.

const queries = await metal.getQueries("index-id");

`deleteOne()`

Delete a single embedding document.

Parameters

Param	Type	Description
`id`	string	The ID of the document to delte.
`indexId`	string	Optional. The ID of the index containing the document.

const document = await metal.deleteOne("documentId-123");

`deleteMany()`

Deletes multiple documents in an index based on their IDs.

Parameters

Param	Type	Description
`id`	string[]	The IDs of the documents to delete.
`indexId`	string	Optional. The ID of the index containing the document.

const document = await metal.deleteOne("documentId-123");

Memory (Motorhead)

App Setup

Param	Type	Description
`apiKey`	string	For Managed. The API Key for your Org. [details](- Create an API Key for Authentication.
`clientId`	string	For Managed.The Client ID for your Org. [details](- Create an API Key for Authentication.
`baseUrl`	string	For Self-hosted. The URL path to your motorhead instance

import { Motorhead } from "@getmetal/metal-sdk";

// Managed
const motorhead = new Motorhead({ apiKey: "apiKey", clientId: "clientId" });

// Self-hosted
const motorhead = new Motorhead({
  baseUrl: "https://motorhead.yourdomain.com",
});

`addMemory()`

interface Memory {
  messages: {
    content: string;
    role: "AI" | "Human";
  };
  context: string;
}

Param	Type	Description
`sessionId`	string	The ID of the session. If the session does not exist, it will create one
`memory`	Memory[]	A memory payload to update the session memory

const memoryPayload = {
  messages: [
    { role: "Human", content: "Who is the best vocalist of all time?" },
    { role: "AI", content: "Ozzy!" },
  ],
  context:
    "User ask what can he eat in Colombia. The AI responds arepas are really nice",
};

await motorhead.addMemory("session-id", memoryPayload);

`getMemory()`

Param	Type	Description
`sessionId`	string	The ID of the session to retrieve memory for

await motorhead.getMemory("session-id");

`deleteMemory()`

Param	Type	Description
`sessionId`	string	The ID of the session to delete memory for

await motorhead.deleteMemory("session-id");

Datasources

`addDatasource()`

Add a new Datasource to your Metal instance.

Parameters

Name	Type	Description
`name`	string	Name of the Datasource.
`sourcetype`	string	Type of the source. It can either be ‘File’ or ‘Text’.
`autoExtract`	boolean	Flag indicating whether auto-extraction is enabled.
`metadataFields`	array	An array of fields specifying which attributes you wish to extract. Each object should have `name`, `type`, and `description` properties.

Metadata Fields

Name	Type	Description
`name`	string	Name of the attribute you wish to extract.
`type`	string	Type of the attribute (e.g., “String”, “Number”).
`description`	string	Brief description or example of the attribute.
`autoExtract`	boolean	Determines if attribute will be auto extracted from content or not.

const dataSourcePayload = {
    name: "my datasource",
    sourcetype: "File",
    autoExtract: true,
    metadataFields: [
      {
        name: "band",
        type: "String",
        description: "Which heavy metal band is represented by the iconic mascot Eddie?",
        autoExtract: true,
      }
    ]
};

const response = await metal.addDatasource(datasourcePayload);

`updateDatasource()`

Parameters

Name	Type	Description
`datasourceId`	string	Identifier of the Datasource you want to update.
`name`	string	Updated name of the Datasource.
`sourcetype`	string	Updated type of the source. Either ‘File’ or ‘Text’.
`autoExtract`	boolean	Updated flag indicating whether auto-extraction is enabled.
`metadataFields`	array	Updated fields specifying which attributes you wish to extract.

const updatedDatasourcePayload = {
    name: "updated_datasource",
    sourcetype: "Text",
    autoExtract: false,
    metadataFields: [
        {
            name: "song",
            type: "String",
            description: "Which was Iron Maiden's first single?"
        }
    ]
};

const response = await Metal.updateDatasource("existing_dataSourceId", updatedDataSourcePayload);

`getDatasource()`

Parameters

Name	Type	Description
`dataSourceId`	string	Identifier of the Datasource you want to retrieve information about.

const datasourceId = "existing_datasourceId";
const response = await Metal.getDatasource(datasourceId);

`getAllDatasources()`

Parameters

Name	Type	Description
`limit`	number	(Optional) The maximum number of Datasources to return. Default is 10, with a maximum of 100.
`page`	number	(Optional) The page number for pagination. Should be a positive integer up to 100.

const limit = 10;
const page = 2;

const response = await Metal.getAllDatasources({ limit, page });

`deleteDatasource()`

Parameters

Name	Type	Description
`datasourceId`	string	The ID of the Datasource you want to delete.

const datasourceId = 'your_data_source_id';
const response = await Metal.deleteDatasource(datasourceId);

Data Entities

`addDataEntity()`

Parameters

Name	Type	Description
`datasourceId`	string	The ID of the datasource where the file belongs.
`filepath`	string	The local file path of the file to upload.
`metadata`	object	Additional Metadata that isn’t extracted.

Example

const datasourceId = 'your_datasource_id';
const filePath = './file_path.csv';

const results = await metal.addDataEntity({
  datasource: datasourceId,
  filepath,
  metadata: {
    band: 'Iron Maiden',
    song: 'The Trooper',
  },
});

`getDataEntity()`

Parameters

Name	Type	Description
`id`	string	The ID of the data entity you want to retrieve.

const dataEntityId = 'your_dataentity_id';

const dataEntity = await metal.getDataEntity(dataEntityId);

`getAllDataEntities()`

Parameters

Name	Type	Description
`datasourceID`	string	The ID of the datasource for which you want to list the data entities.
`limit`	number	(Optional) The maximum number of data entities to return. Default is 10, with a maximum of 100.
`page`	number	(Optional) The page number for pagination. Should be a positive integer up to 100.

const datasourceID = 'your_datasource_id';
const page = 1;
const limit = 10;

const dataEntities = await Metal.listDataEntities(datasourceID, page, limit);

`deleteDataEntity()`

Parameters

Name	Type	Description
`id`	string	The ID of the data entity you want to delete.

Example

const dataEntityID = 'your_dataentity_id';

const result = await Metal.deleteDataEntity(dataEntityID);

Checkout the code on Github

Introduction

Getting Started

Products

API Reference

Platform

Tools

Guides

Node SDK

​Installation

​Retrieval

​App Setup

​addApp()

​Parameters

​getApp()

​Parameters

​getApps()

​updateApp()

​Parameters

​addIndex()

​Parameters

​Filters

​getIndex()

​Parameters

​index()

​Parameters

​indexMany()

​Parameters

​search()

​Parameters

​getOne()

​Parameters

​getMany()

​Parameters

​getQueries()

​Parameters

​deleteOne()

​Parameters

​deleteMany()

​Parameters

​Memory (Motorhead)

​App Setup

​addMemory()

​getMemory()

​deleteMemory()

​Datasources

​addDatasource()

​Parameters

​Metadata Fields

​updateDatasource()

​Parameters

​getDatasource()

​Parameters

​getAllDatasources()

​Parameters

​deleteDatasource()

​Parameters

​Data Entities

​addDataEntity()

​Parameters

​Example

​getDataEntity()

​Parameters

​getAllDataEntities()

​Parameters

​deleteDataEntity()

​Parameters

​Example

Installation

Retrieval

App Setup

`addApp()`

Parameters

`getApp()`

Parameters

`getApps()`

`updateApp()`

Parameters

`addIndex()`

Parameters

Filters

`getIndex()`

Parameters

`index()`

Parameters

`indexMany()`

Parameters

`search()`

Parameters

`getOne()`

Parameters

`getMany()`

Parameters

`getQueries()`

Parameters

`deleteOne()`

Parameters

`deleteMany()`

Parameters

Memory (Motorhead)

App Setup

`addMemory()`

`getMemory()`

`deleteMemory()`

Datasources

`addDatasource()`

Parameters

Metadata Fields

`updateDatasource()`

Parameters

`getDatasource()`

Parameters

`getAllDatasources()`

Parameters

`deleteDatasource()`

Parameters

Data Entities

`addDataEntity()`

Parameters

Example

`getDataEntity()`

Parameters

`getAllDataEntities()`

Parameters

`deleteDataEntity()`

Parameters

Example