Vertesia Events API

openapi: 3.2.0
info:
  title: Vertesia Events 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: Events
paths:
  /events/stream:
    get:
      operationId: StreamEventDeliveries
      tags:
      - Events
      summary: Stream event deliveries
      description: 'Opens a Server-Sent Events stream of recent, new, and changed event delivery rows filtered by category, action, resource type, resource id, and status.


        **Required permissions:** `workflow:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: number
      - name: event_id
        in: query
        required: false
        schema:
          type: string
      - name: resource_id
        in: query
        required: false
        schema:
          type: string
      - name: resource_type
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: event_category
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - content
            - workflow
            - security
            - billing
            - system
            - external
        style: form
        explode: true
      - name: action
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: outbox_status
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - routing
            - routed
            - partially_routed
            - failed
            - dropped
        style: form
        explode: true
      - name: since_event_id
        in: query
        required: false
        schema:
          type: string
      - name: since_created_at
        in: query
        required: false
        schema:
          type: string
      - name: include_event
        in: query
        required: false
        schema:
          type: boolean
      - name: poll_interval_ms
        in: query
        required: false
        schema:
          type: number
      responses:
        '200':
          description: Server-sent event delivery envelopes.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ServerSentEventsResponse'
        '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:
      - workflow:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/events.ts
        className: EventsResource
        methodName: streamDeliveries
  /events/deliveries/search:
    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: SearchEventDeliveries
      tags:
      - Events
      summary: Search event deliveries
      description: 'Lists recent event outbox rows with their materialized delivery intents for the current project.


        **Required permissions:** `workflow:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      parameters: []
      responses:
        '200':
          description: Recent event delivery state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventDeliveriesResponse'
        '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:
      - workflow:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/events.ts
        className: EventDeliveriesResource
        methodName: searchDeliveries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListEventDeliveriesPayload'
  /events/deliveries/queue-summary:
    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: GetEventDeliveryQueueSummary
      tags:
      - Events
      summary: Get event delivery queue summary
      description: 'Summarizes outbox routing backlog and non-succeeded delivery intents for the current project, grouped by subscription and delivery target type.


        **Required permissions:** `workflow:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      parameters: []
      responses:
        '200':
          description: Current event delivery queue state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDeliveryQueueSummaryResponse'
        '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:
      - workflow:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/events.ts
        className: EventDeliveriesResource
        methodName: queueSummary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventDeliveryQueueSummaryPayload'
  /events/deliveries/cancel:
    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: CancelEventDeliveryIntents
      tags:
      - Events
      summary: Cancel queued event delivery intents
      description: 'Cancels matching pending and retrying delivery intents for the current project and deployment environment through a server-side watermark. Active deliveries and later events are not changed.


        **Required permissions:** `workflow:run`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:run
      parameters: []
      responses:
        '200':
          description: Queued event delivery cancellation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelEventDeliveryIntentsResponse'
        '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:
      - workflow:run
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/events.ts
        className: EventDeliveriesResource
        methodName: cancelQueuedDeliveries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelEventDeliveryIntentsPayload'
components:
  schemas:
    EventDeliveryQueueSortField:
      type: string
      enum:
      - subscription_name
      - queued
      - active
      - failed
      - oldest
    EventDeliveryIntentStatus:
      type: string
      enum:
      - pending
      - evaluating
      - starting
      - running
      - succeeded
      - retrying
      - failed
      - cancelled
      - skipped
    EventOutboxStatus:
      type: string
      enum:
      - pending
      - routing
      - routed
      - partially_routed
      - failed
      - dropped
    ListEventDeliveriesPayload:
      type: object
      properties:
        limit:
          type: number
        event_id:
          type: string
        resource_id:
          type: string
        subscription_id:
          type: string
        status:
          type: array
          items:
            $ref: '#/components/schemas/EventDeliveryIntentStatus'
        outbox_status:
          type: array
          items:
            $ref: '#/components/schemas/EventOutboxStatus'
        event_category:
          type: array
          items:
            $ref: '#/components/schemas/EventCategory'
          description: Filter by outbox event category (e.g. external, content).
        action:
          type: array
          items:
            type: string
          description: Filter by outbox action (e.g. opened, created).
        resource_type:
          type: array
          items:
            type: string
          description: Filter by outbox resource type (e.g. github_issue, content_object).
        sort_by:
          $ref: '#/components/schemas/EventDeliverySortField'
          description: Sort field (default created_at).
        sort_order:
          type: string
          enum:
          - asc
          - desc
          description: Sort order (default desc).
      additionalProperties: false
    EventCategory:
      type: string
      enum:
      - content
      - workflow
      - security
      - billing
      - system
      - external
    EventOutboxQueueSummary:
      type: object
      properties:
        total:
          type: number
        active:
          type: number
        failed:
          type: number
        dropped:
          type: number
        by_status:
          $ref: '#/components/schemas/NumberValueMap'
        oldest_active_at:
          type: string
      required:
      - total
      - active
      - failed
      - dropped
      - by_status
      additionalProperties: false
    EventDeliveryQueueSummaryResponse:
      type: object
      properties:
        generated_at:
          type: string
        outbox:
          $ref: '#/components/schemas/EventOutboxQueueSummary'
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/EventDeliveryQueueSubscriptionSummary'
      required:
      - generated_at
      - outbox
      - deliveries
      additionalProperties: false
    EventPriority:
      type: string
      enum:
      - high
      - normal
      - low
    EventDeliverySummary:
      type: object
      properties:
        event_id:
          type: string
        event_category:
          $ref: '#/components/schemas/EventCategory'
        action:
          type: string
        resource_type:
          type: string
        resource_id:
          type: string
        source:
          type: string
        priority:
          $ref: '#/components/schemas/EventPriority'
        status:
          $ref: '#/components/schemas/EventOutboxStatus'
        matched_subscription_count:
          type: number
        materialized_intent_count:
          type: number
        routing_attempt_count:
          type: number
        routing_error:
          type:
          - string
          - 'null'
        routed_at:
          type:
          - string
          - 'null'
        created_at:
          type: string
        updated_at:
          type: string
        intents:
          type: array
          items:
            $ref: '#/components/schemas/EventDeliveryIntentSummary'
      required:
      - event_id
      - event_category
      - action
      - resource_type
      - resource_id
      - source
      - priority
      - status
      - matched_subscription_count
      - materialized_intent_count
      - routing_attempt_count
      - created_at
      - updated_at
      - intents
      additionalProperties: false
    EventDeliveryQueueSummaryPayload:
      type: object
      properties:
        subscription_id:
          type: string
        target_type:
          type: array
          items:
            type: string
            enum:
            - workflow
            - webhook
            - app
            - agent
            - process
        sort_by:
          $ref: '#/components/schemas/EventDeliveryQueueSortField'
        sort_order:
          type: string
          enum:
          - asc
          - desc
      additionalProperties: false
    EventDeliveryQueueFailureSummary:
      type: object
      properties:
        intent_id:
          type: string
        event_id:
          type: string
        status:
          $ref: '#/components/schemas/EventDeliveryIntentStatus'
        attempt_count:
          type: number
        last_error:
          type:
          - string
          - 'null'
        updated_at:
          type: string
      required:
      - intent_id
      - event_id
      - status
      - attempt_count
      - updated_at
      additionalProperties: false
    NumberValueMap:
      type: object
      additionalProperties:
        type: number
    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
    EventDeliveryIntentSummary:
      type: object
      properties:
        id:
          type: string
        event_id:
          type: string
        subscription_id:
          type: string
        subscription_name:
          type: string
        target_type:
          type: string
          enum:
          - workflow
          - webhook
          - app
          - agent
          - process
        workflow_class:
          type:
          - string
          - 'null'
        priority:
          $ref: '#/components/schemas/EventPriority'
        status:
          $ref: '#/components/schemas/EventDeliveryIntentStatus'
        attempt_count:
          type: number
        workflow_id:
          type:
          - string
          - 'null'
        workflow_run_id:
          type:
          - string
          - 'null'
        response_status:
          type:
          - number
          - 'null'
        last_error:
          type:
          - string
          - 'null'
        next_attempt_at:
          type:
          - string
          - 'null'
        started_at:
          type:
          - string
          - 'null'
        completed_at:
          type:
          - string
          - 'null'
        semantic_evaluation:
          anyOf:
          - $ref: '#/components/schemas/SemanticEvaluationRecord'
          - type: 'null'
        created_at:
          type: string
        updated_at:
          type: string
      required:
      - id
      - event_id
      - subscription_id
      - subscription_name
      - target_type
      - priority
      - status
      - attempt_count
      - created_at
      - updated_at
      additionalProperties: false
    ServerSentEventsResponse:
      type: string
    SemanticEvaluationStatus:
      type: string
      enum:
      - pending
      - running
      - matched
      - not_matched
      - error
    ListEventDeliveriesResponse:
      type: object
      properties:
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/EventDeliverySummary'
      required:
      - deliveries
      additionalProperties: false
    SemanticEvaluationRecord:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SemanticEvaluationStatus'
        evaluator_type:
          type: string
          enum:
          - interaction
          - agent
        mode:
          $ref: '#/components/schemas/SemanticConditionMode'
        matched:
          type: boolean
        rationale:
          type: string
        error:
          type: string
        workflow_id:
          type: string
          description: Temporal workflow id of the evaluation agent run (agent evaluator only).
        agent_run_id:
          type: string
        evaluated_at:
          type: string
      required:
      - status
      - evaluator_type
      - mode
      additionalProperties: false
    SemanticConditionMode:
      type: string
      enum:
      - enforce
      - shadow
    CancelEventDeliveryIntentsResponse:
      type: object
      properties:
        environment:
          type: string
          description: Deployment environment whose queue was changed.
        cleared_through:
          type: string
          format: date-time
          description: Server-side watermark; intents created after this time were not changed.
        cancelled:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Pending or retrying intents moved to the cancelled terminal state.
        active_untouched:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Matching evaluating, starting, or running intents left for normal reconciliation.
      required:
      - environment
      - cleared_through
      - cancelled
      - active_untouched
      additionalProperties: false
    EventDeliveryQueueSubscriptionSummary:
      type: object
      properties:
        subscription_id:
          type: string
        subscription_name:
          type: string
        target_type:
          type: string
          enum:
          - workflow
          - webhook
          - app
          - agent
          - process
        total:
          type: number
        queued:
          type: number
        deferred:
          type: number
        active:
          type: number
        failed:
          type: number
        skipped:
          type: number
        max_attempt_count:
          type: number
        oldest_queued_at:
          type: string
        oldest_deferred_at:
          type: string
        latest_failure:
          $ref: '#/components/schemas/EventDeliveryQueueFailureSummary'
      required:
      - subscription_id
      - subscription_name
      - target_type
      - total
      - queued
      - deferred
      - active
      - failed
      - skipped
      - max_attempt_count
      additionalProperties: false
    CancelEventDeliveryIntentsPayload:
      type: object
      properties:
        subscription_id:
          type: string
          minLength: 1
          description: Restrict cancellation to one subscription.
        target_type:
          minItems: 1
          type: array
          items:
            type: string
            enum:
            - workflow
            - webhook
            - app
            - agent
            - process
          description: Restrict cancellation to one or more delivery target types.
      additionalProperties: false
    EventDeliverySortField:
      type: string
      enum:
      - created_at
      - status
      - resource_type
      - event_category
      - action
  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