Vertesia Workflow Rules API

openapi: 3.2.0
info:
  title: Vertesia Workflow Rules 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: Workflow Rules
  description: Workflow rules bind named endpoints and execution defaults to workflow definitions so they can be triggered consistently.
paths:
  /workflows/rules:
    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
    get:
      operationId: ListWorkflowRules
      tags:
      - Workflow Rules
      summary: List workflow rules
      description: 'Lists workflow rules available in the current project.


        **Required permissions:** Any of `workflow:read`, `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      - OAuth2:
        - workflow:admin
      parameters: []
      responses:
        '200':
          description: Workflow rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRuleItemArray'
        '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
      - workflow:admin
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/workflows.ts
        className: WorkflowsResource
        methodName: list
    post:
      operationId: CreateWorkflowRule
      tags:
      - Workflow Rules
      summary: Create a workflow rule
      description: 'Creates a new workflow rule or updates an existing one through the legacy upsert path.


        **Required permissions:** `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:admin
      parameters: []
      responses:
        '200':
          description: The created or updated workflow rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRule'
        '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:admin
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/workflows.ts
        className: WorkflowsResource
        methodName: createOrUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRulePayload'
  /workflows/rules/{ruleId}:
    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
    put:
      operationId: UpdateWorkflowRule
      tags:
      - Workflow Rules
      summary: Update a workflow rule
      description: 'Updates an existing workflow rule.


        **Required permissions:** `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:admin
      parameters:
      - name: ruleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated workflow rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRule'
        '409':
          description: The workflow rule was changed after the caller read it.
        '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:admin
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/workflows.ts
        className: WorkflowRuleResource
        methodName: doPut
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowRulePayload'
    get:
      operationId: GetWorkflowRule
      tags:
      - Workflow Rules
      summary: Retrieve a workflow rule
      description: 'Retrieves a workflow rule by ID.


        **Required permissions:** Any of `workflow:read`, `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      - OAuth2:
        - workflow:admin
      parameters:
      - name: ruleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested workflow rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRule'
        '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
      - workflow:admin
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/workflows.ts
        className: WorkflowRuleResource
        methodName: doGet
    delete:
      operationId: DeleteWorkflowRule
      tags:
      - Workflow Rules
      summary: Delete a workflow rule
      description: 'Deletes a workflow rule.


        **Required permissions:** `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:admin
      parameters:
      - name: ruleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted workflow rule status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCountResult'
        '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:admin
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/workflows.ts
        className: WorkflowRuleResource
        methodName: doDelete
components:
  schemas:
    UpdateWorkflowRulePayload:
      type: object
      properties:
        expected_edit_revision:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: Edit revision returned by the last read. Stale revisions are rejected with HTTP 409. Omit for legacy last-write-wins behavior.
        match:
          type: object
          additionalProperties: true
        config:
          type: object
          additionalProperties: true
          description: Activities configuration if any.
        debug:
          type: boolean
          default: false
          description: Debug mode for the rule
        customer_override:
          type: boolean
          description: Customer override for the rule When set to true the rule will not be updated by the system
        task_queue:
          type: string
          description: Optional task queue name to use when starting workflows for this rule
        event_subscription_migration_status:
          type: string
          enum:
          - migrated
          - unsupported_match
          - failed
          description: Event subscription migration status for legacy workflow-rule cutover.
        event_subscription_migration_error:
          type: string
          description: Migration failure or unsupported-match reason, when applicable.
        input_type:
          $ref: '#/components/schemas/WorkflowRuleInputType'
        description:
          type: string
          description: Optional detailed description of the object
        tags:
          type: array
          items:
            type: string
          description: Optional array of categorization tags
        updated_by:
          type: string
          description: Identifier of the user who last modified the object
        created_by:
          type: string
          description: Identifier of the user who created the object
        endpoint:
          type: string
        name:
          type: string
          description: Human-readable name or title
      description: Fields to change on a workflow rule. All optional.
    WorkflowRuleInputType:
      type: string
      enum:
      - single
      - multiple
      - none
    WorkflowRuleItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object
        edit_revision:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: Monotonic edit revision used to detect concurrent updates.
        name:
          type: string
          description: Human-readable name or title
        description:
          type: string
          description: Optional detailed description of the object
        tags:
          type: array
          items:
            type: string
          description: Optional array of categorization tags
        updated_by:
          type: string
          description: Identifier of the user who last modified the object
        created_by:
          type: string
          description: Identifier of the user who created the object
        created_at:
          type: string
          description: ISO timestamp of when the object was created
        updated_at:
          type: string
          description: ISO timestamp of when the object was last updated
        endpoint:
          type: string
        input_type:
          $ref: '#/components/schemas/WorkflowRuleInputType'
      required:
      - id
      - edit_revision
      - name
      - updated_by
      - created_by
      - created_at
      - updated_at
      - endpoint
      - input_type
      additionalProperties: false
    CreateWorkflowRulePayload:
      type: object
      properties:
        match:
          type: object
          additionalProperties: true
        config:
          type: object
          additionalProperties: true
          description: Activities configuration if any.
        debug:
          type: boolean
          default: false
          description: Debug mode for the rule
        customer_override:
          type: boolean
          description: Customer override for the rule When set to true the rule will not be updated by the system
        task_queue:
          type: string
          description: Optional task queue name to use when starting workflows for this rule
        event_subscription_migration_status:
          type: string
          enum:
          - migrated
          - unsupported_match
          - failed
          description: Event subscription migration status for legacy workflow-rule cutover.
        event_subscription_migration_error:
          type: string
          description: Migration failure or unsupported-match reason, when applicable.
        input_type:
          $ref: '#/components/schemas/WorkflowRuleInputType'
        description:
          type: string
          description: Optional detailed description of the object
        tags:
          type: array
          items:
            type: string
          description: Optional array of categorization tags
        updated_by:
          type: string
          description: Identifier of the user who last modified the object
        created_by:
          type: string
          description: Identifier of the user who created the object
        endpoint:
          type: string
        name:
          type: string
          description: Human-readable name or title
      required:
      - endpoint
      - name
      additionalProperties: false
    WorkflowRule:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object
        edit_revision:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: Monotonic edit revision used to detect concurrent updates.
        name:
          type: string
          description: Human-readable name or title
        description:
          type: string
          description: Optional detailed description of the object
        tags:
          type: array
          items:
            type: string
          description: Optional array of categorization tags
        updated_by:
          type: string
          description: Identifier of the user who last modified the object
        created_by:
          type: string
          description: Identifier of the user who created the object
        created_at:
          type: string
          description: ISO timestamp of when the object was created
        updated_at:
          type: string
          description: ISO timestamp of when the object was last updated
        endpoint:
          type: string
        input_type:
          $ref: '#/components/schemas/WorkflowRuleInputType'
        match:
          type: object
          additionalProperties: true
        config:
          type: object
          additionalProperties: true
          description: Activities configuration if any.
        debug:
          type: boolean
          default: false
          description: Debug mode for the rule
        customer_override:
          type: boolean
          description: Customer override for the rule When set to true the rule will not be updated by the system
        task_queue:
          type: string
          description: Optional task queue name to use when starting workflows for this rule
        event_subscription_migration_status:
          type: string
          enum:
          - migrated
          - unsupported_match
          - failed
          description: Event subscription migration status for legacy workflow-rule cutover.
        event_subscription_migration_error:
          type: string
          description: Migration failure or unsupported-match reason, when applicable.
      required:
      - id
      - edit_revision
      - name
      - updated_by
      - created_by
      - created_at
      - updated_at
      - endpoint
      - input_type
      additionalProperties: false
    DeleteCountResult:
      type: object
      properties:
        id:
          type: string
        count:
          type: number
      required:
      - id
      - count
      additionalProperties: false
    WorkflowRuleItemArray:
      type: array
      items:
        $ref: '#/components/schemas/WorkflowRuleItem'
    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