Bem Review Queue API

openapi: 3.1.0
info:
  title: Bem Buckets Review Queue 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: Review Queue
  description: "The reviewer-facing read surface for entity curation, available on the\ndashboard (JWT) only.\n\n- **`GET /v3/review-queue`** returns a cursor-paginated set of entities\n  awaiting curation, scoped to your account+environment (and optional\n  `bucket`). Each row is a full entity plus a small preview (up to 2) of\n  its first mentions, so a reviewer can triage without opening every\n  entity.\n\nFilters AND together. `status` (repeatable) defaults to the pre-terminal\nstates `extracted` + `proposed` when omitted. `type` (repeatable `ety_…`\nIDs) matches the entity's *effective* type — its assigned type id, or, for\nentities with no assigned type, its bem-inferred type name. `assignedTo`\n(`me` or a `usr_…` ID) restricts to entities whose effective type the user\nreviews. `since` (RFC3339) filters by creation time. Pagination is\ncursor-based on `entityID` ascending; default limit 50, maximum 200."
paths:
  /v3/review-queue:
    get:
      operationId: v3-list-review-queue
      summary: List Review Queue
      description: '**List entities awaiting curation, for a human reviewer''s queue.**


        Returns a cursor-paginated set of entities scoped to your

        account+environment (and optional `bucket`), each carrying a small preview

        of its first mentions so a reviewer can triage without opening every

        entity. All filters AND together.


        - **`status`** (repeatable) restricts to the given lifecycle states.

        Omitting it defaults to the pre-terminal states `extracted` and

        `proposed`.

        - **`type`** (repeatable, `ety_...` IDs) matches the entity''s *effective*

        type: an entity matches when its assigned type is one of these IDs, or it

        has no assigned type and its bem-inferred type name matches one of them.

        - **`assignedTo`** (`me` or a `usr_...` ID) restricts to entities whose

        effective type the given user reviews. `me` resolves to the calling user.

        - **`since`** (RFC3339) restricts to entities created at or after the time.


        Pagination is cursor-based on `entityID` ascending; default limit is 50,

        maximum 200.'
      parameters:
      - name: status
        in: query
        required: false
        description: Restrict to these lifecycle states. Defaults to `extracted` + `proposed`.
        schema:
          type: array
          items:
            type: string
      - name: type
        in: query
        required: false
        description: Restrict to entities whose effective type is one of these `ety_...` IDs.
        schema:
          type: array
          items:
            type: string
      - name: assignedTo
        in: query
        required: false
        description: '`me` or a `usr_...` ID — restrict to entities whose effective type that user reviews.'
        schema:
          type: string
        explode: false
      - name: since
        in: query
        required: false
        description: RFC3339 timestamp — restrict to entities created at or after this time.
        schema:
          type: string
        explode: false
      - name: cursor
        in: query
        required: false
        description: Cursor — an `entityID` defining your place in the list.
        schema:
          type: string
        explode: false
      - name: bucket
        in: query
        required: false
        description: Optional bucket public ID (`bkt_...`) to scope to. Omit for all buckets.
        schema:
          type: string
        explode: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 200
          default: 50
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewQueueResponseV3'
      tags:
      - Review Queue
components:
  schemas:
    ReviewQueueMentionV3:
      type: object
      required:
      - mentionID
      - entityID
      - referenceID
      - page
      - surface
      - createdAt
      properties:
        mentionID:
          type: string
          description: Public ID (`emn_...`) of this mention.
        entityID:
          type: string
          description: Public ID (`ent_...`) of the entity this mention resolves to.
        referenceID:
          type: string
          description: The user-provided document handle this mention came from.
        transformationID:
          type: string
          description: Public ID of the parse transformation that produced this mention, when known.
        page:
          type: integer
          format: int32
          description: 1-indexed page number within the source document.
        sectionLabel:
          type: string
          description: The parse-emitted section label this mention sat under, when present.
        surface:
          type: string
          description: The exact surface string Parse extracted on the page.
        createdAt:
          type: string
          format: date-time
          description: When this mention was recorded.
      description: A single per-document occurrence of an entity, used in review-queue previews.
    ReviewQueueEntityV3:
      type: object
      required:
      - entityID
      - canonical
      - type
      - mentionCount
      - surfaceForms
      - createdAt
      - updatedAt
      - status
      - previewMentions
      properties:
        entityID:
          type: string
          description: Public ID (`ent_...`) of the entity.
        canonical:
          type: string
          description: The canonical (longest / most descriptive) surface form.
        type:
          type: string
          description: The effective type name (assigned override if set, else bem-inferred).
        description:
          type: string
          description: Free-form description of the entity, when present.
        mentionCount:
          type: integer
          format: int32
          description: Total mentions across all parsed documents.
        surfaceForms:
          type: array
          items:
            type: string
          description: Distinct surface forms that have resolved to this entity.
        createdAt:
          type: string
          format: date-time
          description: When the entity was created.
        updatedAt:
          type: string
          format: date-time
          description: When the entity was last updated.
        status:
          type: string
          description: 'Curation lifecycle state: `extracted`, `proposed`, `approved`, `rejected`.'
        typeID:
          type: string
          description: Public ID (`ety_...`) of the customer-assigned type, when one is set.
        validatedAt:
          type: string
          format: date-time
          description: When a human approved/rejected the entity. Omitted while un-validated.
        validatedByUserID:
          type: string
          description: Public ID (`usr_...`) of the user who validated the entity, when known.
        previewMentions:
          type: array
          items:
            $ref: '#/components/schemas/ReviewQueueMentionV3'
          description: 'A capped preview (up to 2) of the entity''s first mentions, ordered by

            page then time, so a reviewer can triage without opening each entity.'
      description: 'One row of the review queue: an entity plus a small preview of its mentions.'
    ReviewQueueResponseV3:
      type: object
      required:
      - entities
      - hasMore
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/ReviewQueueEntityV3'
          description: The page of entities awaiting curation.
        hasMore:
          type: boolean
          description: Whether more rows exist beyond this page.
        nextCursor:
          type: string
          description: Opaque cursor to pass as `?cursor=` for the next page. Empty when `hasMore` is false.
      description: '`GET /v3/review-queue` response. Cursor-paginated by `entityID` ascending.'
  securitySchemes:
    API Key:
      type: apiKey
      in: header
      name: x-api-key
      description: Authenticate using API Key in request header