Bem Collections API
Collections are named groups of embedded items used by Enrich functions for semantic search. Each collection is referenced by a `collectionName`, which supports dot notation for hierarchical paths (e.g. `customers.premium.vip`). Names must contain only letters, digits, underscores, and dots, and each segment must start with a letter or underscore. ## Items Items carry either a string or a JSON object in their `data` field. When items are added or updated, their `data` is embedded asynchronously — `POST /v3/collections/items` and `PUT /v3/collections/items` return immediately with a `pending` status and an `eventID` that can be correlated with webhook notifications once processing completes. ## Listing and hierarchy Use `GET /v3/collections` with `parentCollectionName` to list collections under a path, or `collectionNameSearch` for a case-insensitive substring match. `GET /v3/collections/items` retrieves a specific collection's items; pass `includeSubcollections=true` to fold in items from all descendant collections. ## Token counting Use `POST /v3/collections/token-count` to check whether texts fit within the embedding model's 8,192-token-per-text limit before submitting them for embedding.
openapi: 3.1.0
info:
title: Bem Buckets Collections API
version: 1.0.0
description: "Buckets are named partitions of the knowledge graph within an\naccount+environment. Entities, mentions, and relations are scoped to a\nbucket so a single account+environment can host multiple isolated graphs\n— for example one per data source or workspace.\n\nEvery account+environment has exactly one **default** bucket, used by\nunscoped flows. The default bucket can be renamed but never deleted.\n\nUse these endpoints to create, list, fetch, rename, and delete buckets:\n\n- **`POST /v3/buckets`** creates a non-default bucket.\n- **`GET /v3/buckets`** lists buckets with cursor pagination\n (`startingAfter` / `endingBefore` over `bucketID`).\n- **`PATCH /v3/buckets/{bucketID}`** updates `name` and/or `description`.\n- **`DELETE /v3/buckets/{bucketID}`** soft-deletes a bucket. A non-empty\n bucket is rejected with `409 Conflict` unless `?cascade=true` is\n passed; the default bucket can never be deleted."
servers:
- url: https://api.bem.ai
description: US Region API
variables: {}
- url: https://api.eu1.bem.ai
description: EU Region API
variables: {}
security:
- API Key: []
tags:
- name: Collections
description: 'Collections are named groups of embedded items used by Enrich functions for semantic search.
Each collection is referenced by a `collectionName`, which supports dot notation for
hierarchical paths (e.g. `customers.premium.vip`). Names must contain only letters,
digits, underscores, and dots, and each segment must start with a letter or underscore.
## Items
Items carry either a string or a JSON object in their `data` field. When items are added
or updated, their `data` is embedded asynchronously — `POST /v3/collections/items` and
`PUT /v3/collections/items` return immediately with a `pending` status and an `eventID`
that can be correlated with webhook notifications once processing completes.
## Listing and hierarchy
Use `GET /v3/collections` with `parentCollectionName` to list collections under a path,
or `collectionNameSearch` for a case-insensitive substring match. `GET /v3/collections/items`
retrieves a specific collection''s items; pass `includeSubcollections=true` to fold in items
from all descendant collections.
## Token counting
Use `POST /v3/collections/token-count` to check whether texts fit within the embedding
model''s 8,192-token-per-text limit before submitting them for embedding.'
paths:
/v3/collections:
delete:
operationId: v3-delete-collection
summary: Delete a Collection
parameters:
- name: collectionName
in: query
required: true
description: 'The name/path of the collection to delete. Must use only letters, digits, underscores, and dots.
Each segment must start with a letter or underscore.'
schema:
type: string
responses:
'200':
description: The request has succeeded.
'404':
description: The server cannot find the requested resource.
tags:
- Collections
get:
operationId: v3-list-collections
summary: List Collections
parameters:
- name: parentCollectionName
in: query
required: false
description: 'Optional filter to list only collections under a specific parent collection path.
For example, "customers" will return "customers", "customers.premium", "customers.premium.vip", etc.'
schema:
type: string
- name: collectionNameSearch
in: query
required: false
description: 'Optional substring search filter for collection names (case-insensitive).
For example, "premium" will match "customers.premium", "products.premium", etc.'
schema:
type: string
- name: page
in: query
required: false
description: Page number for pagination
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
required: false
description: Number of collections per page
schema:
type: integer
minimum: 1
maximum: 100
default: 50
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListCollectionsResponseV3'
tags:
- Collections
post:
operationId: v3-create-collection
summary: Create a Collection
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionResponseV3'
examples:
The created collection:
summary: The created collection
value:
collectionID: cl_2N6gH8ZKCmvb6BnFcGqhKJ98VzP
collectionName: product_catalog
itemCount: 0
createdAt: '2024-10-20T15:30:00Z'
updatedAt: '2024-10-20T15:30:00Z'
tags:
- Collections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionRequestV3'
examples:
Create empty collection:
summary: Create empty collection
value:
collectionName: product_catalog
/v3/collections/items:
delete:
operationId: v3-delete-collection-item
summary: Delete an item from a Collection
parameters:
- name: collectionName
in: query
required: true
description: 'The name/path of the collection. Must use only letters, digits, underscores, and dots.
Each segment must start with a letter or underscore.'
schema:
type: string
- name: collectionItemID
in: query
required: true
description: The unique identifier of the item to delete
schema:
type: string
responses:
'204':
description: There is no content to send for this request, but the headers may be useful.
'404':
description: The server cannot find the requested resource.
tags:
- Collections
get:
operationId: v3-get-collection
summary: Get a Collection
parameters:
- name: collectionName
in: query
required: true
description: 'The name/path of the collection. Must use only letters, digits, underscores, and dots.
Each segment must start with a letter or underscore.'
schema:
type: string
- name: page
in: query
required: false
description: Page number for pagination
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
required: false
description: Number of items per page
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: includeSubcollections
in: query
required: false
description: 'When true, includes items from all subcollections under the specified collection path.
For example, querying "customers" with this flag will return items from "customers",
"customers.premium", "customers.premium.vip", etc.'
schema:
type: boolean
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionResponseV3'
'404':
description: The server cannot find the requested resource.
tags:
- Collections
post:
operationId: v3-add-collection-items
summary: Add new items to a Collection
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/AddCollectionItemsResponseV3'
example:
status: pending
message: Collection items are being processed asynchronously
eventID: evt_2N6gH8ZKCmvb6BnFcGqhKJ98VzP
'400':
description: The server could not understand the request due to invalid syntax.
'404':
description: The server cannot find the requested resource.
'500':
description: Server error
tags:
- Collections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddCollectionItemsRequestV3'
examples:
Add new items (objects):
summary: Add new items (objects)
value:
collectionName: product_catalog
items:
- data:
sku: SKU-11111
name: Deluxe Component
category: Hardware
price: 299.99
- data:
sku: SKU-22222
name: Standard Part
category: Tools
price: 49.99
Add new items (strings):
summary: Add new items (strings)
value:
collectionName: product_catalog
items:
- data: 'SKU-12345: Industrial Widget'
- data: 'SKU-67890: Premium Gear'
put:
operationId: v3-update-collection-items
summary: Update existing items in a Collection
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCollectionItemsResponseV3'
example:
status: pending
message: Collection items are being updated asynchronously
eventID: evt_3M7hI9ALDnwc7CoGdHriLK09WaQ
'400':
description: The server could not understand the request due to invalid syntax.
'404':
description: The server cannot find the requested resource.
'500':
description: Server error
tags:
- Collections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCollectionItemsRequestV3'
examples:
Update existing items:
summary: Update existing items
value:
collectionName: product_catalog
items:
- collectionItemID: clitm_2N6gH8ZKCmvb6BnFcGqhKJ98VzP
data: 'SKU-12345: Updated Industrial Widget - Premium Edition'
- collectionItemID: clitm_3M7hI9ALDnwc7CoGdHriLK09WaQ
data:
sku: SKU-67890
name: Updated Premium Gear
category: Hardware
price: 399.99
/v3/collections/token-count:
post:
operationId: v3-count-tokens
summary: Count tokens for texts
description: 'Count the number of tokens in the provided texts using the BGE M3 tokenizer.
This is useful for checking if texts will fit within the embedding model''s token limit
(8,192 tokens per text) before sending them for embedding.'
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CountTokensResponseV3'
'400':
description: The server could not understand the request due to invalid syntax.
'500':
description: Server error
tags:
- Collections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CountTokensRequestV3'
components:
schemas:
CountTokensRequestV3:
type: object
required:
- texts
properties:
texts:
type: array
items:
type: string
description: One or more texts to tokenize.
description: Request body for counting tokens against the embedding tokenizer.
AddCollectionItemsResponseV3:
type: object
required:
- status
- message
- eventID
properties:
status:
type: string
enum:
- pending
description: Processing status
message:
type: string
description: Status message
eventID:
type: string
description: Event ID for tracking this operation. Use this to correlate with webhook notifications.
addedCount:
type: integer
description: Number of new items added (only present in synchronous mode, deprecated)
items:
type: array
items:
$ref: '#/components/schemas/CollectionItemV3'
description: Array of items that were added (only present in synchronous mode, deprecated)
description: Response after queuing items for async processing
CollectionItemV3:
type: object
required:
- collectionItemID
- data
- createdAt
- updatedAt
properties:
collectionItemID:
type: string
description: Unique identifier for the item
data:
oneOf:
- type: string
- type: object
unevaluatedProperties: {}
description: The data stored in this item
createdAt:
type: string
format: date-time
description: When the item was created
updatedAt:
type: string
format: date-time
description: When the item was last updated
description: A single item in a collection
CollectionMetadataV3:
type: object
required:
- collectionID
- collectionName
- itemCount
- createdAt
properties:
collectionID:
type: string
description: Unique identifier for the collection
collectionName:
type: string
description: The collection name/path. Only letters, digits, underscores, and dots are allowed.
itemCount:
type: integer
description: Number of items in the collection
createdAt:
type: string
format: date-time
description: When the collection was created
updatedAt:
type: string
format: date-time
description: When the collection was last updated
description: Collection metadata without items
CountTokensResponseV3:
type: object
properties:
token_counts:
type: array
items:
$ref: '#/components/schemas/CountTokensItemV3'
description: Per-text tokenization results in the same order as the request.
total_tokens:
type: integer
description: Sum of `token_count` across all texts.
max_token_limit:
type: integer
description: Maximum tokens allowed per text by the embedding model.
texts_exceeding_limit:
type: integer
description: Number of input texts that exceed `max_token_limit`.
description: Response for the token count endpoint.
CollectionItemUpdateV3:
type: object
required:
- collectionItemID
- data
properties:
collectionItemID:
type: string
description: Unique identifier for the item to update
data:
oneOf:
- type: string
- type: object
unevaluatedProperties: {}
description: The updated data to be embedded and stored (string or JSON object)
description: Data for updating an existing item in a collection
CreateCollectionRequestV3:
type: object
required:
- collectionName
properties:
collectionName:
type: string
description: 'Unique name/path for the collection. Supports dot notation for hierarchical paths.
- Only letters (a-z, A-Z), digits (0-9), underscores (_), and dots (.) are allowed
- Each segment (between dots) must start with a letter or underscore (not a digit)
- Segments cannot consist only of digits
- Each segment must be 1-256 characters
- No leading, trailing, or consecutive dots
- Invalid names are rejected with a 400 Bad Request error
**Valid Examples:**
- ''product_catalog''
- ''orders.line_items.sku''
- ''customer_data''
- ''price_v2''
**Invalid Examples:**
- ''product-catalog'' (contains hyphen)
- ''123items'' (starts with digit)
- ''items..data'' (consecutive dots)
- ''order#123'' (contains invalid character #)'
description: Request to create a new collection
UpdateCollectionItemsRequestV3:
type: object
required:
- collectionName
- items
properties:
collectionName:
type: string
description: 'The name/path of the collection. Must use only letters, digits, underscores, and dots.
Each segment must start with a letter or underscore.'
items:
type: array
items:
$ref: '#/components/schemas/CollectionItemUpdateV3'
minItems: 1
maxItems: 100
description: Array of items to update (maximum 100 items per request)
description: Request to update existing items in a collection
ListCollectionsResponseV3:
type: object
required:
- collections
- page
- limit
- totalCount
- totalPages
properties:
collections:
type: array
items:
$ref: '#/components/schemas/CollectionMetadataV3'
description: List of collections
page:
type: integer
description: Current page number
limit:
type: integer
description: Number of collections per page
totalCount:
type: integer
description: Total number of collections
totalPages:
type: integer
description: Total number of pages
description: Response for listing collections
AddCollectionItemsRequestV3:
type: object
required:
- collectionName
- items
properties:
collectionName:
type: string
description: 'The name/path of the collection. Must use only letters, digits, underscores, and dots.
Each segment must start with a letter or underscore.'
items:
type: array
items:
$ref: '#/components/schemas/CollectionItemInputV3'
minItems: 1
maxItems: 100
description: Array of items to add (maximum 100 items per request)
description: Request to add new items to a collection
CountTokensItemV3:
type: object
properties:
index:
type: integer
description: Zero-based position of this entry in the request `texts` array.
token_count:
type: integer
description: Number of tokens produced by the tokenizer.
exceeds_limit:
type: boolean
description: True if `token_count` exceeds the embedding model's per-text limit.
char_count:
type: integer
description: Character count of the input text.
description: Per-text token count result.
UpdateCollectionItemsResponseV3:
type: object
required:
- status
- message
- eventID
properties:
status:
type: string
enum:
- pending
description: Processing status
message:
type: string
description: Status message
eventID:
type: string
description: Event ID for tracking this operation. Use this to correlate with webhook notifications.
updatedCount:
type: integer
description: Number of items updated (only present in synchronous mode, deprecated)
items:
type: array
items:
$ref: '#/components/schemas/CollectionItemV3'
description: Array of items that were updated (only present in synchronous mode, deprecated)
description: Response after queuing items for async update
CollectionItemInputV3:
type: object
required:
- data
properties:
data:
oneOf:
- type: string
- type: object
unevaluatedProperties: {}
description: The data to be embedded and stored (string or JSON object)
description: Data for creating a new item in a collection
CollectionResponseV3:
type: object
required:
- collectionID
- collectionName
- itemCount
- createdAt
properties:
collectionID:
type: string
description: Unique identifier for the collection
collectionName:
type: string
description: The collection name/path. Only letters, digits, underscores, and dots are allowed.
itemCount:
type: integer
description: Number of items in the collection
items:
type: array
items:
$ref: '#/components/schemas/CollectionItemV3'
description: List of items in the collection (when fetching collection details)
page:
type: integer
description: Current page number
limit:
type: integer
description: Number of items per page
totalPages:
type: integer
description: Total number of pages
createdAt:
type: string
format: date-time
description: When the collection was created
updatedAt:
type: string
format: date-time
description: When the collection was last updated
description: Collection details
securitySchemes:
API Key:
type: apiKey
in: header
name: x-api-key
description: Authenticate using API Key in request header