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