Vertesia Event Ingest Channels API

openapi: 3.2.0
info:
  title: Vertesia Event Ingest Channels 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: Event Ingest Channels
paths:
  /events/channels:
    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: ListEventIngestChannels
      tags:
      - Event Ingest Channels
      summary: List event ingest channels
      description: '**Required permissions:** `workflow:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      parameters: []
      responses:
        '200':
          description: Event ingest channels of the current project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventIngestChannelArray'
        '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/event-ingest-channels.ts
        className: EventIngestChannelsResource
        methodName: listChannels
    post:
      operationId: CreateEventIngestChannel
      tags:
      - Event Ingest Channels
      summary: Create an event ingest channel
      description: 'Creates an inbound channel for publishing external events. The ingest token is returned once in the response and cannot be retrieved later.


        **Required permissions:** `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:admin
      parameters: []
      responses:
        '200':
          description: The created event ingest channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventIngestChannelMutationResponse'
        '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/event-ingest-channels.ts
        className: EventIngestChannelsResource
        methodName: createChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventIngestChannelPayload'
  /events/channels/{channelId}:
    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: GetEventIngestChannel
      tags:
      - Event Ingest Channels
      summary: Retrieve an event ingest channel
      description: '**Required permissions:** `workflow:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:read
      parameters:
      - name: channelId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested event ingest channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventIngestChannel'
        '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/event-ingest-channels.ts
        className: EventIngestChannelResource
        methodName: getChannel
    put:
      operationId: UpdateEventIngestChannel
      tags:
      - Event Ingest Channels
      summary: Update an event ingest channel
      description: 'Updates a channel. Set rotate_token to true to rotate the ingest token: the new token is returned once in the response. Create or rotate the signing secret separately from rotating the ingest token.


        **Required permissions:** `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:admin
      parameters:
      - name: channelId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated event ingest channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventIngestChannelMutationResponse'
        '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/event-ingest-channels.ts
        className: EventIngestChannelResource
        methodName: updateChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEventIngestChannelPayload'
    delete:
      operationId: DeleteEventIngestChannel
      tags:
      - Event Ingest Channels
      summary: Delete an event ingest channel
      description: '**Required permissions:** `workflow:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - workflow:admin
      parameters:
      - name: channelId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted event ingest channel 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/event-ingest-channels.ts
        className: EventIngestChannelResource
        methodName: deleteChannel
components:
  schemas:
    EventPriority:
      type: string
      enum:
      - high
      - normal
      - low
    EventIngestChannelArray:
      type: array
      items:
        $ref: '#/components/schemas/EventIngestChannel'
    CreateEventIngestChannelPayload:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        source:
          type: string
          description: Defaults to a slug derived from the name.
        default_action:
          type: string
        default_resource_type:
          type: string
        transform:
          $ref: '#/components/schemas/EventIngestTransform'
        signature:
          $ref: '#/components/schemas/EventIngestSignatureConfig'
        priority:
          $ref: '#/components/schemas/EventPriority'
        enabled:
          type: boolean
      required:
      - name
      additionalProperties: false
    EventIngestSignatureAlgorithm:
      type: string
      enum:
      - sha256
      - sha1
      description: 'How an ingest channel authenticates inbound requests in addition to the channel ingest token:

        - none (default): token only.

        - hmac: the sender signs the raw request body with a shared secret (GitHub/Stripe style) and the   server verifies the signature. The token may then be optional (`token_optional`).'
    EventIngestSignatureEncoding:
      type: string
      enum:
      - hex
      - base64
    EventIngestTransform:
      type: object
      properties:
        action_path:
          type: string
          description: Dot-path to the value used as `event.action`, e.g. `event.type`.
        resource_type_path:
          type: string
          description: Dot-path to the value used as `event.resource_type`.
        resource_id_path:
          type: string
          description: Dot-path to the value used as `event.resource_id`.
        event_type_header:
          type: string
          description: Request **header** carrying the event family (e.g. GitHub's `x-github-event`), captured into `event.details.event_type`. Lets subscriptions and `resource_rules` discriminate event shapes when one channel receives heterogeneous payloads whose `action` alone is ambiguous (e.g. `created` for both an issue comment and a PR review comment).
        resource_rules:
          type: array
          items:
            $ref: '#/components/schemas/EventIngestResourceRule'
          description: Ordered conditional rules for `resource_type` + `resource_id` (first match wins). Used when a single `resource_id_path` can't serve every payload shape. Falls back to `resource_type_path` / `resource_id_path` / channel defaults when no rule matches.
        idempotency_key_path:
          type: string
          description: Dot-path to a deduplication key (same semantics as `idempotency_key`).
        idempotency_key_header:
          type: string
          description: Request **header** to use as the deduplication key when the body has no stable per-delivery id — e.g. GitHub App's `x-github-delivery`, unique per delivery for all event types, which is the only reliable dedup key when one App webhook delivers heterogeneous payloads (issues + comments) to a single channel. Lower precedence than `idempotency_key_path`.
        timestamp_path:
          type: string
          description: Dot-path to an ISO 8601 event timestamp.
        static_details:
          type: object
          additionalProperties: true
          description: Static fields merged into `event.details`.
      additionalProperties: false
      description: Declarative mapping from a raw third-party webhook body to platform event fields, for senders that cannot shape their payload (GitHub, Slack, DocuSign, Salesforce, ...). Each `*_path` is a dot-path into the JSON body (array indices supported, e.g. `commits.0.id`). Extracted values override the channel defaults; the full raw body is always preserved under `event.details.payload`.
    EventIngestChannelMutationResponse:
      type: object
      properties:
        channel:
          $ref: '#/components/schemas/EventIngestChannel'
        ingest_token:
          type: string
          description: Returned once on creation or rotation; it cannot be retrieved later.
        signing_secret:
          type: string
          description: Returned once on creation or rotation of the signing secret; it cannot be retrieved later.
      required:
      - channel
      additionalProperties: false
    DeleteCountResult:
      type: object
      properties:
        id:
          type: string
        count:
          type: number
      required:
      - id
      - count
      additionalProperties: false
    UpdateEventIngestChannelPayload:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        source:
          type: string
        default_action:
          type: string
        default_resource_type:
          type: string
        transform:
          anyOf:
          - $ref: '#/components/schemas/EventIngestTransform'
          - type: 'null'
          description: Pass null to remove the transform.
        signature:
          anyOf:
          - $ref: '#/components/schemas/EventIngestSignatureConfig'
          - type: 'null'
          description: Pass null to remove signature verification.
        priority:
          $ref: '#/components/schemas/EventPriority'
        enabled:
          type: boolean
        rotate_token:
          type: boolean
          description: Request rotation of the channel ingest token on update.
        rotate_signing_secret:
          type: boolean
          description: Request rotation of the HMAC signing secret on update.
      additionalProperties: false
    EventIngestResourceRule:
      type: object
      properties:
        event_type:
          type: array
          items:
            type: string
          description: Match when the captured `event_type` (see `event_type_header`) is one of these.
        when_path_exists:
          type: string
          description: Match only when this dot-path resolves to a defined, non-null value (e.g. `issue.pull_request`).
        when_path_absent:
          type: string
          description: Match only when this dot-path is undefined/null.
        resource_type:
          type: string
          description: '`resource_type` to set when this rule matches.'
        resource_id_path:
          type: string
          description: '`resource_id` from a single dot-path.'
        resource_id_template:
          type: string
          description: '...or a composed `resource_id` from a `{{dot.path}}` template against the body, e.g. `{{repository.full_name}}#{{pull_request.number}}`. Takes precedence over `resource_id_path`.'
      additionalProperties: false
      description: 'A conditional rule for deriving `resource_type` + `resource_id` from the body, evaluated in order (first match wins) when a single dot-path can''t serve every payload shape a channel receives. A sender whose one webhook delivers heterogeneous events (e.g. a GitHub App: issues, issue comments, PR reviews) needs different thread identities per event family; these rules express that without baking provider knowledge into the server.'
    EventIngestChannel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        account_id:
          type: string
        project_id:
          type: string
        source:
          type: string
          description: Source label stamped on ingested events as `external:<source>`.
        enabled:
          type: boolean
        default_action:
          type: string
          description: Action used when the ingest payload does not specify one.
        default_resource_type:
          type: string
          description: Resource type used when the ingest payload does not specify one.
        transform:
          $ref: '#/components/schemas/EventIngestTransform'
          description: Optional mapping from raw third-party payloads to event fields.
        signature:
          $ref: '#/components/schemas/EventIngestSignatureConfig'
          description: Optional HMAC signature verification config.
        priority:
          $ref: '#/components/schemas/EventPriority'
        has_token:
          type: boolean
          description: 'Server-managed: whether an ingest token is active for this channel.'
        token_hint:
          type: string
          description: 'Server-managed: last characters of the active token, for identification.'
        created_by:
          type: string
        updated_by:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      required:
      - id
      - name
      - account_id
      - project_id
      - source
      - enabled
      - priority
      - has_token
      additionalProperties: false
      description: 'An inbound channel that lets external systems publish events into the platform event bus. Events ingested through a channel get `event_category: ''external''` and `source: ''external:<source>''`, and are matched against event subscriptions like any other platform event.'
    EventIngestSignatureConfig:
      type: object
      properties:
        header:
          type: string
          description: Request header carrying the signature, e.g. `x-hub-signature-256`.
        algorithm:
          $ref: '#/components/schemas/EventIngestSignatureAlgorithm'
        encoding:
          $ref: '#/components/schemas/EventIngestSignatureEncoding'
        prefix:
          type: string
          description: Literal prefix stripped from the header value before comparison, e.g. `sha256=`.
        has_secret:
          type: boolean
          description: 'Server-managed: whether a signing secret is stored for this channel.'
        secret_hint:
          type: string
          description: 'Server-managed: label/hint of the stored signing secret.'
      required:
      - header
      additionalProperties: false
      description: 'Optional HMAC signature verification for an ingest channel. When configured, the server recomputes `HMAC(algorithm, signing_secret, rawBody)` and compares it (timing-safe) to the value in `header`, after stripping `prefix`. Covers GitHub-style `X-Hub-Signature-256: sha256=<hex>` and a plain Salesforce Apex-callout HMAC.'
    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