Vertesia Bulk Operations API

openapi: 3.2.0
info:
  title: Vertesia Bulk Operations API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Bulk Operations
  description: Bulk Operation endpoints create, update, delete, or retag many content objects in a single request.
paths:
  /operations:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: RunBulkContentOperation
      tags:
      - Bulk Operations
      summary: Run a bulk content operation
      description: 'Runs a bulk create, update, delete, or change-type operation across multiple content objects.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters: []
      responses:
        '200':
          description: Bulk operation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - content:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/index.ts
        className: ApiRoot
        methodName: postBulkOperation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkOperationPayload'
components:
  schemas:
    BulkObjectCreateResult:
      type: object
      properties:
        operation:
          type: string
          const: create
        status:
          type: string
          enum:
          - in_progress
          - completed
          - failed
        created:
          type: number
          description: Number of documents successfully created
        objects:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              index:
                type: number
              external_id:
                type: string
            required:
            - id
            additionalProperties: false
          description: Successfully created objects with their IDs
        failed:
          type: array
          items:
            type: object
            properties:
              external_id:
                type: string
              index:
                type: number
              error:
                type: string
            required:
            - index
            - error
            additionalProperties: false
          description: Objects that failed to create
      required:
      - operation
      - status
      - created
      - objects
      - failed
      additionalProperties: false
    BulkOperationResponse:
      oneOf:
      - $ref: '#/components/schemas/BulkOperationResult'
      - $ref: '#/components/schemas/BulkObjectCreateResult'
      - $ref: '#/components/schemas/BulkObjectUpdateResult'
      - $ref: '#/components/schemas/BulkObjectDeleteResult'
      discriminator:
        propertyName: operation
        mapping:
          generic: '#/components/schemas/BulkOperationResult'
          create: '#/components/schemas/BulkObjectCreateResult'
          update: '#/components/schemas/BulkObjectUpdateResult'
          delete: '#/components/schemas/BulkObjectDeleteResult'
      type: object
      required:
      - operation
    BulkObjectDeleteResult:
      type: object
      properties:
        operation:
          type: string
          const: delete
        status:
          type: string
          enum:
          - in_progress
          - completed
          - failed
        deleted:
          type: number
          description: Number of documents deleted (including revisions)
        failed:
          type: array
          items:
            type: string
          description: IDs that were not found or user had no permission to delete
      required:
      - operation
      - status
      - deleted
      - failed
      additionalProperties: false
    BulkObjectUpdateResult:
      type: object
      properties:
        operation:
          type: string
          const: update
        status:
          type: string
          enum:
          - in_progress
          - completed
          - failed
        updated:
          type: number
          description: Number of documents successfully updated
        failed:
          type: array
          items:
            type: string
          description: IDs that were not found, not authorized, or failed to update
      required:
      - operation
      - status
      - updated
      - failed
      additionalProperties: false
    BulkOperationPayload:
      type: object
      properties:
        name:
          type: string
          enum:
          - change_type
          - create
          - delete
          - start_workflow
          - update
          description: The operation name
        ids:
          type: array
          items:
            type: string
          description: The IDs of the objects to operate on
        params:
          type: object
          additionalProperties: true
          description: The operation parameters.
      required:
      - name
      - ids
      - params
      additionalProperties: false
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
    BulkOperationResult:
      type: object
      properties:
        operation:
          type: string
          const: generic
        status:
          type: string
          enum:
          - in_progress
          - completed
          - failed
      required:
      - operation
      - status
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections