@unbody-io/admin-api

v0.0.5

Published

9 months ago

The `@unbody-io/admin-api` package provides a TypeScript client for interacting with the Unbody Admin API.

0High
0Medium
0Low

Overview

The @unbody-io/admin-api package provides a TypeScript client for interacting with the Unbody Admin API.

Installation

To install the package, use npm or yarn:

# using npm
npm install @unbody-io/admin-api

# using yarn
yarn add @unbody-io/admin-api

Authentication

To authenticate with the Unbody Admin API, you need an admin key, which can be generated from Unbody's dashboard under Settings > Admin Keys.

The UnbodyAdminAPI class supports three methods for authentication:

Base64 encoded adminKey
Username and password (admin key ID and secret)
Access token (Bearer token)

Example:

import { UnbodyAdminAPI } from '@unbody-io/admin-api'

const admin = new UnbodyAdminAPI({
  auth: {
    // Auth with base64 encoded admin key
    adminKey: 'Basic ...',

    // or Username & Password
    username: 'admin-key-id',
    password: 'admin-key-secret',

    // or Access Token
    accessToken: 'Bearer ...',
  },
})

Example Usage

To create a new project:

const { data } = await admin.projects.create({
  body: {
    name: 'My New Project',
    settings: {
      textVectorizer: {
        name: 'text2vec-contextionary',
      },
    },
  },
})

To list projects with filters:

await admin.projects.list({
  filter: {
    state: {
      $in: ['initialized', 'created'],
    },
    name: {
      $like: '%something%',
    },
  },
})

List of Endpoints

Below is a list of endpoints available for interacting with Unbody entities such as projects, API keys, sources, and webhooks.

Projects

List Projects

const response = await admin.projects.list({
  filter: {
    name: {
      $like: '%example%',
    },
  },
  limit: 10,
  offset: 0,
})
console.log(response.data)

Method: GET
Path: /projects
Filterable Fields: Reference
Pagination Parameters: limit, offset, sort

Create Project

const response = await admin.projects.create({
  body: {
    name: 'New Project Name',
    settings: {
      textVectorizer: {
        name: 'text2vec-contextionary',
      },
    },
  },
})
console.log(response.data)

Method: POST
Path: /projects

For more details on configuring project settings, see the Project Settings Reference.

Update Project

const response = await admin.projects.patch({
  projectId: 'your-project-id',
  body: {
    name: 'Updated Project Name',
  },
})
console.log(response.data)

Method: PATCH
Path: /projects/{projectId}

Delete Project

await admin.projects.delete({
  projectId: 'your-project-id',
})
console.log('Project deleted successfully')

Method: DELETE
Path: /projects/{projectId}

Restore Project

const response = await admin.projects.restore({
  projectId: 'your-project-id',
})
console.log(response.data)

Method: POST
Path: /projects/{projectId}/restore

API Keys

Create Admin API Key

const response = await admin.apiKeys.create({
  body: {
    name: 'New Admin API Key',
    expiresAfter: '2024-12-31',
  },
})
console.log(response.data)

Method: POST
Path: /api-keys

Delete Admin API Key

await admin.apiKeys.delete({
  id: 'api-key-id',
})
console.log('Admin API Key deleted successfully')

Method: DELETE
Path: /api-keys/{id}

Project API Keys

Create Project API Key

const { data } = await admin.projects.createApiKey({
  projectId: 'your-project-id',
  body: {
    name: 'New Project API Key',
  },
})

console.log('Secret: ', data.data.key)

Method: POST
Path: /projects/{projectId}/api-keys

Delete Project API Key

await admin.projects.deleteApiKey({
  projectId: 'your-project-id',
  id: 'api-key-id',
})

Method: DELETE
Path: /projects/{projectId}/api-keys

Project Webhooks

List Project Webhooks

const response = await admin.projects.listWebhooks({
  projectId: 'your-project-id',
})
console.log(response.data)

Method: GET
Path: /projects/{projectId}/webhooks
Filterable Fields: Reference

Create Project Webhook

const response = await admin.projects.createWebhook({
  projectId: 'your-project-id',
  body: {
    url: 'https://your-webhook-url.com',
  },
})
console.log(response.data)

Method: POST
Path: /projects/{projectId}/webhooks

Delete Project Webhook

await admin.projects.deleteWebhook({
  projectId: 'your-project-id',
  webhookId: 'webhook-id',
})
console.log('Webhook deleted successfully')

Method: DELETE
Path: /projects/{projectId}/webhooks/{webhookId}

Project Sources

List Project Sources

const response = await admin.projects.listSources({
  projectId: 'your-project-id',
})
console.log(response.data)

Method: GET
Path: /projects/{projectId}/sources
Filterable Fields: Reference

Create Source

const response = await admin.projects.createSource({
  projectId: 'your-project-id',
  body: {
    name: 'New Source',
    provider: 'github_issues',
  },
})
console.log(response.data)

Method: POST
Path: /projects/{projectId}/sources

Update Source

const response = await admin.projects.patchSource({
  projectId: 'your-project-id',
  sourceId: 'source-id',
  body: {
    name: 'Updated Source Name',
  },
})
console.log(response.data)

Method: PATCH
Path: /projects/{projectId}/sources/{sourceId}

Delete Source

await admin.projects.deleteSource({
  projectId: 'your-project-id',
  sourceId: 'source-id',
})

Method: DELETE
Path: /projects/{projectId}/sources/{sourceId}

Source Indexing

Initialize Source

await admin.projects.initializeSource({
  projectId: 'your-project-id',
  sourceId: 'source-id',
})

Method: POST
Path: /projects/{projectId}/sources/{sourceId}/indexing/initialize

Trigger Manual Update

await admin.projects.updateSource({
  projectId: 'your-project-id',
  sourceId: 'source-id',
})

Method: POST
Path: /projects/{projectId}/sources/{sourceId}/indexing/update

Rebuild Source

await admin.projects.rebuildSource({
  projectId: 'your-project-id',
  sourceId: 'source-id',
})

Method: POST
Path: /projects/{projectId}/sources/{sourceId}/indexing/rebuild

Filterable Fields

Project Filterable Fields

| Field | Type | Filter Operators | | ----------------------------------------- | ------ | ------------------------------------------------------------ | | name | string | String Filter Operators | | state | enum | Enum Filter Operators; | | pausedAt | Date | Date Filter Operators | | restoredAt | Date | Date Filter Operators | | createdAt | Date | Date Filter Operators | | updatedAt | Date | Date Filter Operators |

Project State Possible Values

created
initializing
initialized
paused
pausing
restoring

Source Filterable Fields

| Field | Type | Filter Operators | | ---------------------------------------- | ------- | ------------------------------------------------------------ | | name | string | String Filter Operators | | initialized | boolean | Boolean Filter Operators | | state | enum | Enum Filter Operators | | type | enum | Enum Filter Operators | | pausedAt | Date | Date Filter Operators | | restoredAt | Date | Date Filter Operators | | createdAt | Date | Date Filter Operators | | updatedAt | Date | Date Filter Operators |

Source State Possible Values

initializing
updating
deleting
paused
idle

Source Type Possible Values

google_drive
google_calendar
discord
github_branch
github_issues
push_api

Webhook Filterable Fields

| Field | Type | Filter Operators | | ----------- | ---- | ----------------------------------------------- | | createdAt | Date | Date Filter Operators |

Filter Operators

String and Enum Filter Operators

$eq, $ne, $in, $nin, $null, $like

Number Filter Operators

$eq, $ne, $gt, $lt, $gte, $lte, $null

Boolean Filter Operators

$eq, $ne, $null

Date Filter Operators

$gt, $gte, $lt, $lte, $null

Project Settings Reference

Project Settings Fields

textVectorizer
- Defines the text vectorization model used for representing text as vectors, which is essential for search operations.
- name: string - Possible values:
  - text2vec-contextionary
  - text2vec-transformers
  - text2vec-openai-ada-002
  - text2vec-openai-text-embedding-3-large
  - text2vec-openai-text-embedding-small
  - text2vec-cohere-multilingual-v3.0
  - text2vec-cohere-multilingual-light-v3.0
  - text2vec-cohere-english-v3.0
  - text2vec-cohere-english-light-v3.0
  - text2vec-cohere-english-v2.0
  - text2vec-cohere-english-light-v2.0
imageVectorizer
- Sets the model used for representing images as vectors.
- name: string - Possible value:
  - img2vec-neural
qnaProvider
- Defines the provider used for Q&A capabilities within the project.
- name: string - Possible values:
  - qna-transformers
  - qna-openai-gpt-3.5-turbo-instruct
generativeSearch
- name: string - Possible value:
  - generative-unbody
- options
  - model: string - Possible values:
    - gpt-3.5-turbo
    - gpt-4
    - gpt-4-turbo
    - gpt-4o
    - gpt-4o-mini
    - command
    - command-light
    - command-r
    - command-r-plus
    - open-mistral-7b
    - open-mixtral-8x7b
reranker
- Specifies the reranking model used to prioritize search results.
- name: string - Possible values:
  - reranker-transformers
  - reranker-cohere-multilingual-v3.0
  - reranker-cohere-multilingual-v2.0
  - reranker-cohere-english-v3.0
  - reranker-cohere-english-v2.0
spellcheck
- Configures the spellcheck functionality.
- name: string - Possible value:
  - text-spellcheck
autoSummary
- Automatically generates summaries for text content.
- name: string - Possible values:
  - autosum-openai-gpt-3.5-turbo
  - autosum-openai-gpt-4o
  - autosum-openai-gpt-4o-mini
  - autosum-cohere-command-r
autoKeywords
- Extracts keywords from text automatically.
- name: string - Possible values:
  - autokeywords-openai-gpt-3.5-turbo
  - autokeywords-openai-gpt-4o
  - autokeywords-openai-gpt-4o-mini
autoEntities
- Automatically identifies and extracts entities from text.
- name: string - Possible values:
  - autoentities-openai-gpt-3.5-turbo
  - autoentities-openai-gpt-4o
  - autoentities-openai-gpt-4o-mini
autoTopics
- Automatically generates topics from the content.
- name: string - Possible values:
  - autotopics-openai-gpt-3.5-turbo
  - autotopics-openai-gpt-4o
  - autotopics-openai-gpt-4o-mini
autoVision
- Generates captions, labels, and extracts texts from image files.
- name: string - Possible values:
  - autovision-openai-gpt-4o
  - autovision-openai-gpt-4o-mini
  - autovision-openai-gpt-4-turbo
customSchema
- Allows defining custom data schemas for projects.
- name: string - Possible value: customSchema
- options
  - collections: An array of collection definitions, each with the following fields:
    - name: string - The name of the collection in PascalCase format with the suffix Collection (e.g., CustomCollection).
    - fields: An array of field definitions, each including:
      - name: string - Field name in camelCase format.
      - array: boolean - Indicates whether the field is an array.
      - description: string - (Optional) Description of the field.
      - type - Possible types: int, number, text, uuid, date, boolean, object, phoneNumber, geoCoordinates, cref.
      - Additional Field Configurations:
        text field:
        Can have additional properties:
        skipTokenization: boolean - If true, the field will not be tokenized.
        tokenization: enum - Defines the tokenization strategy for the field. Possible values are word, field, lowercase, and whitespace.
        phoneNumber field:
        Input/Output Schema:
        { "input": "020 1234567", // Required. Raw input in string format "defaultCountry": "nl", // Required if only a national number is provided, ISO 3166-1 alpha-2 country code. Only set if explicitly set by the user. "internationalFormatted": "+31 20 1234567", // Read-only string "countryCode": 31, // Read-only unsigned integer, numerical country code "national": 201234567, // Read-only unsigned integer, numerical representation of the national number "nationalFormatted": "020 1234567", // Read-only string "valid": true // Read-only boolean. Whether the parser recognized the phone number as valid }
        geoCoordinates field:
        Input/Output Schema:
        { "latitude": 52.366667, "longitude": 4.9 }
        object field:
        Must have a fields field, which is an array of field definitions. Possible types within the object are: int, number, text, date, boolean, uuid.
        Note: Currently, objects are not vectorized, and filter operators are not supported.
        cref field:
        Must have a refs array where each reference includes:
        collection: string - The collection name being referenced.
        field: string - The foreign collection's field being referenced.
        Available Built-in Collections for cref include:
        ImageBlock's document field
        AudioFile's document field
        VideoFile's document field
  - extend: (Optional) An array of collection and field definitions to extend the built-in schema.
    - name: The name of the collection to extend. Allowed values are:
      - ImageBlock
      - AudioFile
      - VideoFile
      - TextDocument
      - SpreadsheetDocument
      - SubtitleFile
    - fields: An array of field definitions to add to the collection. These definitions follow the same format as custom collections. Extra field names must be in camelCase format and prefixed with an x (e.g., xCustomField).

Example Configuration

Here’s an example of configuring project settings with various options:

{
  "textVectorizer": {
    "name": "text2vec-openai-text-embedding-3-small"
  },
  "spellcheck": {
    "name": "text-spellcheck"
  },
  "reranker": {
    "name": "reranker-cohere-multilingual-v3.0"
  },
  "autoTopics": {
    "name": "autotopics-openai-gpt-4o"
  },
  "autoVision": {
    "name": "autovision-openai-gpt-4o"
  },
  "autoSummary": {
    "name": "autosum-openai-gpt-4o"
  },
  "qnaProvider": {
    "name": "qna-openai-gpt-3.5-turbo-instruct"
  },
  "autoEntities": {
    "name": "autoentities-openai-gpt-4o"
  },
  "autoKeywords": {
    "name": "autokeywords-openai-gpt-4o"
  },
  "generativeSearch": {
    "name": "generative-unbody",
    "options": {
      "model": "gpt-4o"
    }
  },
  "customSchema": {
    "name": "customSchema",
    "options": {
      "collections": [
        {
          "name": "ProfileCollection",
          "fields": [
            {
              "name": "name",
              "type": "text"
            },
            {
              "name": "firstName",
              "type": "text"
            },
            {
              "name": "lastName",
              "type": "text"
            },
            {
              "name": "photos",
              "type": "cref",
              "refs": [
                {
                  "collection": "ImageBlock",
                  "field": "document"
                }
              ]
            },
            {
              "name": "videos",
              "type": "cref",
              "refs": [
                {
                  "collection": "VideoFile",
                  "field": "document"
                }
              ]
            },
            {
              "name": "emailAddress",
              "type": "text",
              "tokenization": "field"
            },
            {
              "name": "phoneNumber",
              "type": "phoneNumber"
            },
            {
              "name": "address",
              "type": "object",
              "fields": [
                {
                  "name": "street",
                  "type": "text"
                },
                {
                  "name": "city",
                  "type": "text"
                },
                {
                  "name": "state",
                  "type": "text"
                },
                {
                  "name": "zip",
                  "type": "text"
                },
                {
                  "name": "country",
                  "type": "text"
                }
              ]
            },
            {
              "name": "addressCoordinates",
              "type": "geoCoordinates"
            }
          ]
        }
      ],
      "extend": [
        {
          "name": "TextDocument",
          "fields": [
            {
              "name": "xExtraField",
              "type": "text"
            }
          ]
        }
      ]
    }
  }
}