openapi: 3.1.0
info:
  title: Bem Buckets Subscriptions 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: Subscriptions
  description: 'Subscriptions wire up notifications for the events your functions and collections produce.


    Most subscriptions target a single function (by `functionName` or `functionID`) or a single

    collection (by `collectionName` or `collectionID`) and select a `type` corresponding to the

    event you want to receive — for example `transform`, `route`, `join`, `evaluation`, `error`,

    `enrich`, or `collection_processing`.


    Entity-lifecycle events are account-wide and target no function or collection. Set `type` to

    one of the following and provide a `webhookURL` (these event types support webhook delivery

    only):


    - `entity_proposed` — an entity entered the `proposed` curation status (queued for review).

    - `entity_validated` — an entity was approved/validated by a reviewer.

    - `entity_rejected` — an entity was rejected by a reviewer.


    Each entity-lifecycle delivery is a JSON POST describing the transition (`entityID`,

    `typeName`, `priorStatus`, `newStatus`, optional `actorUserID` and `reason`, and a

    `timestamp`).


    Deliveries can be sent to any combination of:


    - `webhookURL` — HTTPS endpoint that receives a JSON POST per event.

    - `s3Bucket` + `s3FilePath` — sync output JSON into an AWS S3 prefix you own.

    - `googleDriveFolderID` — drop output JSON into a Google Drive folder.


    Use `disabled: true` to pause delivery without deleting the subscription. Updates follow

    conventional PATCH semantics — only the fields you include are changed.'
paths:
  /v3/subscriptions:
    get:
      operationId: v3-list-subscriptions
      summary: List Subscriptions
      parameters:
      - name: functionNames
        in: query
        required: false
        description: Filters to subscriptions linked to included array of function names.
        schema:
          type: array
          items:
            type: string
          minItems: 1
      - name: limit
        in: query
        required: false
        description: This specifies a limit on the number of objects to return, ranging between 1 and 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: sortOrder
        in: query
        required: false
        description: Specifies sorting behavior. The two options are `asc` and `desc` to sort ascending and descending respectively, with default sort being ascending. Paging works in both directions.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: startingAfter
        in: query
        required: false
        description: A cursor to use in pagination. `startingAfter` is a task ID that defines your place in the list. For example, if you make a list request and receive 50 objects, ending with `sub_2c9AXIj48cUYJtCuv1gsQtHGDzK`, your subsequent call can include `startingAfter=sub_2c9AXIj48cUYJtCuv1gsQtHGDzK` to fetch the next page of the list.
        schema:
          type: string
      - name: endingBefore
        in: query
        required: false
        description: A cursor to use in pagination. `endingBefore` is a task ID that defines your place in the list. For example, if you make a list request and receive 50 objects, starting with `sub_2c9AXIj48cUYJtCuv1gsQtHGDzK`, your subsequent call can include `endingBefore=sub_2c9AXIj48cUYJtCuv1gsQtHGDzK` to fetch the previous page of the list.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionV3'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '401':
          description: Access is unauthorized.
        '500':
          description: Server error
      tags:
      - Subscriptions
    post:
      operationId: v3-create-subscription
      summary: Create a Subscription
      description: Creates a new subscription to listen to transform or error events.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionV3'
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionV3'
  /v3/subscriptions/{subscriptionID}:
    delete:
      operationId: v3-delete-subscription
      summary: Delete a Subscription
      description: Deletes an existing subscription.
      parameters:
      - name: subscriptionID
        in: path
        required: true
        description: ID of the subscription to delete
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
      tags:
      - Subscriptions
    get:
      operationId: v3-get-subscription
      summary: Get a Subscription
      parameters:
      - name: subscriptionID
        in: path
        required: true
        description: ID of the subscription to retrieve.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionV3'
      tags:
      - Subscriptions
    patch:
      operationId: v3-update-subscription
      summary: Update a Subscription
      description: Updates an existing subscription. Follow conventional PATCH behavior, so only included fields will be updated.
      parameters:
      - name: subscriptionID
        in: path
        required: true
        description: ID of the subscription to update
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionV3'
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionV3'
components:
  schemas:
    UpdateSubscriptionV3:
      type: object
      properties:
        name:
          type: string
          description: Name of subscription.
        type:
          type: string
          enum:
          - transform
          - analyze
          - route
          - join
          - split_collection
          - split_item
          - evaluation
          - error
          - payload_shaping
          - enrich
          - collection_processing
          description: Type of subscription.
        disabled:
          type: boolean
          description: Toggles whether subscription is active or not.
        functionName:
          type: string
          description: Unique name of function this subscription listens to.
        webhookURL:
          type: string
          description: URL bem will send webhook requests to.
        s3Bucket:
          type: string
          description: S3 bucket name for syncing output data to AWS S3.
        s3FilePath:
          type: string
          description: S3 file path for syncing output data to AWS S3.
        googleDriveFolderID:
          type: string
          description: Google Drive folder ID for syncing output data to Google Drive.
    SubscriptionV3:
      type: object
      required:
      - name
      - subscriptionID
      - type
      properties:
        name:
          type: string
          description: Name of subscription.
        subscriptionID:
          type: string
          description: The unique identifier of the subscription.
        type:
          type: string
          enum:
          - transform
          - analyze
          - route
          - join
          - split_collection
          - split_item
          - evaluation
          - error
          - payload_shaping
          - enrich
          - collection_processing
          description: Type of subscription.
        functionID:
          type: string
          description: Unique identifier of function this subscription listens to.
        functionName:
          type: string
          description: Unique name of function this subscription listens to.
        collectionID:
          type: string
          description: Unique identifier of collection this subscription listens to.
        collectionName:
          type: string
          description: Name of collection this subscription listens to.
        disabled:
          type: boolean
          description: Toggles whether subscription is active or not.
        webhookURL:
          type: string
          description: URL bem will send webhook requests to.
        s3Bucket:
          type: string
          description: S3 bucket name for syncing output data to AWS S3.
        s3FilePath:
          type: string
          description: S3 file path for syncing output data to AWS S3.
        googleDriveFolderID:
          type: string
          description: Google Drive folder ID for syncing output data to Google Drive.
      title: Subscription
    CreateSubscriptionV3:
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: Name of subscription.
        type:
          type: string
          enum:
          - transform
          - analyze
          - route
          - join
          - split_collection
          - split_item
          - evaluation
          - error
          - payload_shaping
          - enrich
          - collection_processing
          description: Type of subscription.
        functionName:
          type: string
          description: Unique name of function this subscription listens to (required for function-based subscriptions).
        functionID:
          type: string
          description: Unique identifier of function this subscription listens to (alternative to functionName).
        collectionName:
          type: string
          description: Name of collection this subscription listens to (required for collection-based subscriptions).
        collectionID:
          type: string
          description: Unique identifier of collection this subscription listens to (alternative to collectionName).
        disabled:
          type: boolean
          description: Toggles whether subscription is active or not.
        webhookURL:
          type: string
          description: URL bem will send webhook requests to.
        s3Bucket:
          type: string
          description: S3 bucket name for syncing output data to AWS S3.
        s3FilePath:
          type: string
          description: S3 file path for syncing output data to AWS S3.
        googleDriveFolderID:
          type: string
          description: Google Drive folder ID for syncing output data to Google Drive.
  securitySchemes:
    API Key:
      type: apiKey
      in: header
      name: x-api-key
      description: Authenticate using API Key in request header