Vertesia Pending Asks API

openapi: 3.2.0
info:
  title: Vertesia Pending Asks 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: Pending Asks
paths:
  /pending-asks:
    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: RegisterPendingAsk
      tags:
      - Pending Asks
      summary: Register a pending agent question
      description: 'Register a new pending ask.

        Called when an agent calls ask_user.


        **Required permissions:** `workflow:run`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:run
      parameters: []
      responses:
        '200':
          description: Registration result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterPendingAskResponse'
        '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/pending-asks.ts
        className: PendingAsksResource
        methodName: register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterPendingAskRequest'
    get:
      operationId: ListPendingAsks
      tags:
      - Pending Asks
      summary: List pending agent questions
      description: 'List all pending asks for the current project.


        **Required permissions:** Any of `agent_run:read`, `workflow:run`'
      security:
      - bearerAuth: []
      - OAuth2:
        - agent_run:read
      - OAuth2:
        - workflow:run
      parameters: []
      responses:
        '200':
          description: Pending questions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPendingAsksResponse'
        '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:
      - agent_run:read
      - workflow:run
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/pending-asks.ts
        className: PendingAsksResource
        methodName: list
  /pending-asks/{askId}/resolve:
    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: ResolvePendingAsk
      tags:
      - Pending Asks
      summary: Resolve a pending agent question
      description: 'Resolve a pending ask with the user''s response.


        **Required permissions:** `workflow:run`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:run
      parameters:
      - name: askId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resolution result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvePendingAskResponse'
        '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/pending-asks.ts
        className: PendingAsksResource
        methodName: resolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolvePendingAskRequest'
  /pending-asks/{askId}:
    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: GetPendingAsk
      tags:
      - Pending Asks
      summary: Retrieve a pending agent question
      description: 'Get a specific pending ask by ID.


        **Required permissions:** Any of `agent_run:read`, `workflow:run`'
      security:
      - bearerAuth: []
      - OAuth2:
        - agent_run:read
      - OAuth2:
        - workflow:run
      parameters:
      - name: askId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Pending question.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingAskData'
        '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:
      - agent_run:read
      - workflow:run
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/pending-asks.ts
        className: PendingAsksResource
        methodName: retrieve
components:
  schemas:
    RegisterPendingAskRequest:
      type: object
      properties:
        runId:
          type: string
        workflowId:
          type: string
        agentName:
          type: string
        questions:
          type: array
          items:
            type: string
        timeoutHours:
          type: number
        userChannels:
          type: array
          items:
            $ref: '#/components/schemas/UserChannel'
        taskFields:
          type: array
          items:
            $ref: '#/components/schemas/TaskField'
        requestId:
          type: string
      required:
      - runId
      - workflowId
      - agentName
      - questions
      - userChannels
      additionalProperties: false
    EmailChannel:
      type: object
      properties:
        type:
          type: string
          const: email
        to_email:
          type: string
          description: Email address to send agent messages to
        thread_subject:
          type: string
          description: Subject for the email thread (without "Re:" prefix)
        in_reply_to:
          type: string
          description: Message ID for In-Reply-To header (most recent message)
        references:
          type: array
          items:
            type: string
          description: Chain of message IDs for References header
        route_key:
          type: string
          description: Short routing key for reply emails (8-char alphanumeric, stored in Redis)
      required:
      - type
      - to_email
      additionalProperties: false
      description: Email channel configuration with threading support. Used for email-based agent communication.
    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
    RegisterPendingAskResponse:
      type: object
      properties:
        success:
          type: boolean
        askId:
          type: string
        webhookSent:
          type: boolean
        error:
          type: string
      required:
      - success
      additionalProperties: false
    ListPendingAsksResponse:
      type: object
      properties:
        asks:
          type: array
          items:
            $ref: '#/components/schemas/PendingAskData'
      required:
      - asks
      additionalProperties: false
    TaskField:
      type: object
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/TaskFieldType'
        required:
          type: boolean
        label:
          type: string
        options:
          type: array
          items:
            type: string
        default: {}
      required:
      - name
      - type
      additionalProperties: false
    TaskFieldType:
      type: string
      enum:
      - string
      - number
      - boolean
      - select
      - text
    UserChannel:
      oneOf:
      - $ref: '#/components/schemas/EmailChannel'
      - $ref: '#/components/schemas/InteractiveChannel'
      discriminator:
        propertyName: type
        mapping:
          email: '#/components/schemas/EmailChannel'
          interactive: '#/components/schemas/InteractiveChannel'
      type: object
      required:
      - type
    ResolvePendingAskResponse:
      type: object
      properties:
        success:
          type: boolean
        webhookSent:
          type: boolean
        waitDurationMs:
          type: number
        error:
          type: string
      required:
      - success
      additionalProperties: false
    ResolvePendingAskRequest:
      type: object
      properties:
        response:
          type: string
      required:
      - response
      additionalProperties: false
    InteractiveChannel:
      type: object
      properties:
        type:
          type: string
          const: interactive
      required:
      - type
      additionalProperties: false
      description: Interactive (UI chat) channel configuration. Used for real-time chat interface communication.
    PendingAskStatus:
      type: string
      enum:
      - pending
      - resolved
      - expired
    PendingAskData:
      type: object
      properties:
        askId:
          type: string
        runId:
          type: string
        workflowId:
          type: string
        projectId:
          type: string
        accountId:
          type: string
        agentName:
          type: string
        questions:
          type: array
          items:
            type: string
        timeoutHours:
          type: number
        userChannels:
          type: array
          items:
            $ref: '#/components/schemas/UserChannel'
        createdAt:
          type: number
        expiresAt:
          type: number
        status:
          $ref: '#/components/schemas/PendingAskStatus'
        taskId:
          type: string
        resolvedAt:
          type: number
        response:
          type: string
      required:
      - askId
      - runId
      - workflowId
      - projectId
      - accountId
      - agentName
      - questions
      - timeoutHours
      - userChannels
      - createdAt
      - expiresAt
      - 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