Vertesia Content Query API

openapi: 3.2.0
info:
  title: Vertesia Content Query 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: Content Query
paths:
  /query:
    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: ExecuteContentQuery
      tags:
      - Content Query
      summary: Execute a SQL, ES|QL, or Elasticsearch DSL content query
      description: 'Execute a query against the project''s Elasticsearch index


        Security filtering is automatically applied based on the authenticated user''s principals.

        For SQL/ES|QL, a WHERE clause is injected.

        For DSL, a filter clause is added.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters: []
      responses:
        '200':
          description: Query result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentQueryResult'
        '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/query.ts
        className: QueryResource
        methodName: executeQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentQueryPayload'
components:
  schemas:
    ContentQueryResult:
      type: object
      properties:
        type:
          type: string
          enum:
          - sql
          - esql
          - dsl
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
            required:
            - name
            - type
            additionalProperties: false
        rows:
          type: array
          items:
            type: array
            items: {}
        hits:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              score:
                type: number
              source: {}
            required:
            - id
            - score
            - source
            additionalProperties: false
        total:
          type: number
        aggregations:
          type: object
          additionalProperties: true
        cursor:
          type: string
        took:
          type: number
      required:
      - type
      additionalProperties: false
    ContentQueryPayload:
      type: object
      properties:
        sql:
          type: string
        esql:
          type: string
        dsl:
          type: object
          properties:
            query:
              type: object
              additionalProperties: true
            aggs:
              type: object
              additionalProperties: true
            size:
              type: number
            from:
              type: number
            sort:
              type: array
              items:
                type: object
                additionalProperties: true
          additionalProperties: false
        format:
          type: string
          enum:
          - json
          - csv
          - table
      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
  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