The `@unbody-io/admin-api` package provides a TypeScript client for interacting with the Unbody Admin API.
npm install @unbody-io/admin-apiThe @unbody-io/admin-api package provides a TypeScript client for interacting with the Unbody Admin API.
To install the package, use npm or yarn:
``bashusing npm
npm install @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
class supports three methods for authentication:- Base64 encoded
adminKey
- Username and password (admin key ID and secret)
- Access token (Bearer token)Example:
typescript
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 ...',
},
})
`$3
To create a new project:
typescript
const { data } = await admin.projects.create({
body: {
name: 'My New Project',
settings: {
textVectorizer: {
name: 'text2vec-contextionary',
},
},
},
})
`To list projects with filters:
typescript
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.
$3
#### List Projects
typescript
const response = await admin.projects.list({
filter: {
name: {
$like: '%example%',
},
},
limit: 10,
offset: 0,
})
console.log(response.data)
`- Method:
- Path:
- Filterable Fields: Reference
- Pagination Parameters: , offset, sort#### Create Project
typescript
const response = await admin.projects.create({
body: {
name: 'New Project Name',
settings: {
textVectorizer: {
name: 'text2vec-contextionary',
},
},
},
})
console.log(response.data)
`- Method:
- Path: For more details on configuring project settings, see the Project Settings Reference.
#### Update Project
typescript
const response = await admin.projects.patch({
projectId: 'your-project-id',
body: {
name: 'Updated Project Name',
},
})
console.log(response.data)
`- Method:
- Path: #### Delete Project
typescript
await admin.projects.delete({
projectId: 'your-project-id',
})
console.log('Project deleted successfully')
`- Method:
- Path: #### Restore Project
typescript
const response = await admin.projects.restore({
projectId: 'your-project-id',
})
console.log(response.data)
`- Method:
- Path: $3
#### Create Admin API Key
typescript
const response = await admin.apiKeys.create({
body: {
name: 'New Admin API Key',
expiresAfter: '2024-12-31',
},
})
console.log(response.data)
`- Method:
- Path: #### Delete Admin API Key
typescript
await admin.apiKeys.delete({
id: 'api-key-id',
})
console.log('Admin API Key deleted successfully')
`- Method:
- Path: $3
#### Create Project API Key
typescript
const { data } = await admin.projects.createApiKey({
projectId: 'your-project-id',
body: {
name: 'New Project API Key',
},
})console.log('Secret: ', data.data.key)
`- Method:
- Path: #### Delete Project API Key
typescript
await admin.projects.deleteApiKey({
projectId: 'your-project-id',
id: 'api-key-id',
})
`- Method:
- Path: $3
#### List Project Webhooks
typescript
const response = await admin.projects.listWebhooks({
projectId: 'your-project-id',
})
console.log(response.data)
`- Method:
- Path:
- Filterable Fields: Reference#### Create Project Webhook
typescript
const response = await admin.projects.createWebhook({
projectId: 'your-project-id',
body: {
url: 'https://your-webhook-url.com',
},
})
console.log(response.data)
`- Method:
- Path: #### Delete Project Webhook
typescript
await admin.projects.deleteWebhook({
projectId: 'your-project-id',
webhookId: 'webhook-id',
})
console.log('Webhook deleted successfully')
`- Method:
- Path: $3
#### List Project Sources
typescript
const response = await admin.projects.listSources({
projectId: 'your-project-id',
})
console.log(response.data)
`- Method:
- Path:
- Filterable Fields: Reference#### Create Source
typescript
const response = await admin.projects.createSource({
projectId: 'your-project-id',
body: {
name: 'New Source',
provider: 'github_issues',
},
})
console.log(response.data)
`- Method:
- Path: #### Update Source
typescript
const response = await admin.projects.patchSource({
projectId: 'your-project-id',
sourceId: 'source-id',
body: {
name: 'Updated Source Name',
},
})
console.log(response.data)
`- Method:
- Path: #### Delete Source
typescript
await admin.projects.deleteSource({
projectId: 'your-project-id',
sourceId: 'source-id',
})
`- Method:
- Path: $3
#### Initialize Source
typescript
await admin.projects.initializeSource({
projectId: 'your-project-id',
sourceId: 'source-id',
})
`- Method:
- Path: #### Trigger Manual Update
typescript
await admin.projects.updateSource({
projectId: 'your-project-id',
sourceId: 'source-id',
})
`- Method:
- Path: #### Rebuild Source
typescript
await admin.projects.rebuildSource({
projectId: 'your-project-id',
sourceId: 'source-id',
})
`- Method:
- Path: Filterable Fields
$3
| Field | Type | Filter Operators |
| ----------------------------------------- | ------ | ------------------------------------------------------------ |
|
| 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
-
-
-
-
- $3
| Field | Type | Filter Operators |
| ---------------------------------------- | ------- | ------------------------------------------------------------ |
|
| 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
-
-
-
- #### Source Type Possible Values
-
-
-
-
-
- $3
| Field | Type | Filter Operators |
| ----------- | ---- | ----------------------------------------------- |
|
| Date | Date Filter Operators |Filter Operators
$3
-
$eq, $ne, $in, $nin, $null, $like$3
-
, $ne, $gt, $lt, $gte, $lte, $null$3
-
, $ne, $null$3
-
, $gte, $lt, $lte, $nullProject Settings Reference
$3
-
- Defines the text vectorization model used for representing text as vectors, which is essential for search operations.
-
- Possible values:
- text2vec-contextionary
-
-
-
-
-
-
-
-
-
- -
- Sets the model used for representing images as vectors.
-
- Possible value:
- img2vec-neural-
- Defines the provider used for Q&A capabilities within the project.
-
- Possible values:
- qna-transformers
- -
-
- Possible value:
- generative-unbody
-
- - Possible values:
- gpt-3.5-turbo
-
-
-
-
-
-
-
-
-
- -
- Specifies the reranking model used to prioritize search results.
-
- Possible values:
- reranker-transformers
-
-
-
- -
- Configures the spellcheck functionality.
-
- Possible value:
- text-spellcheck-
- Automatically generates summaries for text content.
-
- Possible values:
- autosum-openai-gpt-3.5-turbo
-
-
- -
- Extracts keywords from text automatically.
-
- Possible values:
- autokeywords-openai-gpt-3.5-turbo
-
- -
- Automatically identifies and extracts entities from text.
-
- Possible values:
- autoentities-openai-gpt-3.5-turbo
-
- -
- Automatically generates topics from the content.
-
- Possible values:
- autotopics-openai-gpt-3.5-turbo
-
- -
- Generates captions, labels, and extracts texts from image files.
-
- Possible values:
- autovision-openai-gpt-4o
-
- -
- Allows defining custom data schemas for projects.
-
- Possible value: customSchema
- -
: 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:
`json
{
"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
}
`
- field:
- Input/Output Schema:
`json
{
"latitude": 52.366667,
"longitude": 4.9
}
`
- 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
-
-
-
-
-
- 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 (e.g., xCustomField).$3
Here’s an example of configuring project settings with various options:
`json
{
"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"
}
]
}
]
}
}
}
``