openapi: 3.0.3
info:
  title: Ava Protocol AVS Auth Triggers API
  version: 1.0.0
  description: 'Public REST API for the Ava Protocol AVS aggregator. Exposes workflow

    creation, execution monitoring, smart-wallet management, and related

    operations.


    Authentication is a single credential type — a JWT bearer token — obtained

    either via the wallet-signing flow (`POST /auth:exchange`) or out-of-band

    via the operator-run `create-api-key` CLI. Every request must include

    `Authorization: Bearer <jwt>`.

    '
servers:
- url: https://gateway.avaprotocol.org/api/v1
  description: Production gateway
- url: https://gateway-staging.avaprotocol.org/api/v1
  description: Staging gateway
- url: http://localhost:8080/api/v1
  description: Local dev
security:
- bearerAuth: []
tags:
- name: Triggers
  description: Stand-alone trigger evaluation
paths:
  /triggers:run:
    post:
      tags:
      - Triggers
      summary: Evaluate a trigger definition with inline input
      operationId: runTrigger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunTriggerRequest'
      responses:
        '200':
          description: Trigger evaluation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunTriggerResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    EventTriggerQuery:
      type: object
      description: Single ethereum.FilterQuery — one subscription per query.
      properties:
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/EthereumAddress'
          description: Contract addresses to filter events from. Empty matches any contract.
        topics:
          type: array
          items:
            type: string
            nullable: true
          description: 'Topic filters (`topics[0]` is the event signature, `topics[1..]`

            are indexed parameter values). `null` means wildcard at that

            position.

            '
        maxEventsPerBlock:
          type: integer
          format: int32
          description: Safety ceiling per query per block. Exceeded → task cancelled.
        contractAbi:
          type: array
          items:
            additionalProperties: true
          description: Contract ABI entries (JSON form) for event decoding.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/EventCondition'
          description: Filters applied to decoded event data.
        methodCalls:
          type: array
          items:
            $ref: '#/components/schemas/EventMethodCall'
          description: Method calls used to enrich decoded event data (e.g., `decimals`).
    EventCondition:
      type: object
      description: Predicate evaluated against decoded event data.
      required:
      - fieldName
      - operator
      - value
      properties:
        fieldName:
          type: string
        operator:
          type: string
          enum:
          - eq
          - ne
          - gt
          - gte
          - lt
          - lte
          - contains
        value:
          type: string
          description: 'Value to compare against, encoded as a string. The operator

            parses it according to `fieldType` (e.g. `int256` / `uint256`

            → big.Int, `address` → checksummed hex, `bool` →

            "true"/"false"). Matches the proto `EventCondition.value`,

            which is also a string.

            '
        fieldType:
          type: string
    EthereumAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: Lowercase or checksummed hex EOA / contract address.
      example: '0x82F2Dd9a552a69f2ceD7Ff2D05c43aB8430158FB'
    InputVariables:
      type: object
      additionalProperties: true
      description: 'Free-form key-value bag of values used to resolve `{{variable.path}}`

        template references inside trigger and node configs. Conventional

        well-known keys: `settings.runner` (smart wallet address),

        `settings.chainId` (chain id). camelCase keys; back-compat support

        for snake_case keys exists during the migration window.

        '
    Hex:
      type: string
      pattern: ^0x[a-fA-F0-9]*$
      description: Arbitrary-length hex-encoded byte string.
    EventTrigger:
      allOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - event
          config:
            $ref: '#/components/schemas/EventTriggerConfig'
    TriggerType:
      type: string
      enum:
      - manual
      - fixedTime
      - cron
      - block
      - event
      description: 'Discriminator field for the Trigger union. Mirrors the proto

        `TriggerType` enum but without the `TRIGGER_TYPE_` prefix.

        '
    EventTriggerConfig:
      type: object
      description: Fires when matching on-chain events are observed.
      required:
      - queries
      - chainId
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/EventTriggerQuery'
          minItems: 1
        cooldownSeconds:
          type: integer
          format: int32
          minimum: 0
          description: 'Seconds to wait after a fire before allowing the same task to

            trigger again. Default 300. 0 disables cooldown.

            '
        chainId:
          $ref: '#/components/schemas/ChainId'
          description: Chain to watch events on. Required — a workflow carries no chain to inherit.
    CronTriggerConfig:
      type: object
      description: Fires on one or more cron schedules.
      required:
      - schedules
      properties:
        schedules:
          type: array
          items:
            type: string
            description: Standard cron expression (e.g., `* * * * *`).
          minItems: 1
        timezone:
          type: string
          description: IANA timezone (e.g., `UTC`, `America/New_York`). Default UTC.
    BlockTrigger:
      allOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - block
          config:
            $ref: '#/components/schemas/BlockTriggerConfig'
    FixedTimeTrigger:
      allOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - fixedTime
          config:
            $ref: '#/components/schemas/FixedTimeTriggerConfig'
    RunTriggerRequest:
      type: object
      required:
      - trigger
      properties:
        trigger:
          $ref: '#/components/schemas/Trigger'
        triggerInput:
          $ref: '#/components/schemas/InputVariables'
    RunTriggerResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
        error:
          type: string
        errorCode:
          type: string
        output:
          additionalProperties: true
        metadata:
          additionalProperties: true
    CronTrigger:
      allOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - cron
          config:
            $ref: '#/components/schemas/CronTriggerConfig'
    ManualTriggerConfig:
      type: object
      description: User-initiated trigger; no chain context.
      required:
      - lang
      properties:
        data:
          description: Arbitrary structured payload returned in the trigger output.
          additionalProperties: true
        headers:
          type: object
          additionalProperties:
            type: string
          description: HTTP headers (for webhook testing).
        pathParams:
          type: object
          additionalProperties:
            type: string
          description: Path parameters (for webhook testing).
        lang:
          $ref: '#/components/schemas/Lang'
    Lang:
      type: string
      enum:
      - javascript
      - json
      - graphql
      - handlebars
      description: 'Language/format of an inline payload (e.g., custom code source,

        manual trigger data). Mirrors the proto `Lang` enum minus the

        `LANG_` prefix. Wire values are lowercase.

        '
    BlockTriggerConfig:
      type: object
      description: Fires every N blocks on the target chain.
      required:
      - interval
      - chainId
      properties:
        interval:
          type: integer
          format: int64
          minimum: 1
          description: Fire every N blocks.
        chainId:
          $ref: '#/components/schemas/ChainId'
          description: Chain to watch blocks on. Required — a workflow carries no chain to inherit.
    Trigger:
      type: object
      required:
      - type
      - name
      - config
      properties:
        id:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/TriggerType'
      discriminator:
        propertyName: type
        mapping:
          manual: '#/components/schemas/ManualTrigger'
          fixedTime: '#/components/schemas/FixedTimeTrigger'
          cron: '#/components/schemas/CronTrigger'
          block: '#/components/schemas/BlockTrigger'
          event: '#/components/schemas/EventTrigger'
      oneOf:
      - $ref: '#/components/schemas/ManualTrigger'
      - $ref: '#/components/schemas/FixedTimeTrigger'
      - $ref: '#/components/schemas/CronTrigger'
      - $ref: '#/components/schemas/BlockTrigger'
      - $ref: '#/components/schemas/EventTrigger'
    ManualTrigger:
      allOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - manual
          config:
            $ref: '#/components/schemas/ManualTriggerConfig'
    ChainId:
      type: integer
      format: int64
      description: 'Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On

        chain-aware trigger/node configs this is required and must be a

        configured chain; on query/filter params it is optional.

        '
      example: 11155111
    Problem:
      type: object
      description: 'RFC 7807 problem+json. Returned as `application/problem+json` on any

        4xx/5xx response. `type` and `title` describe the error class; `detail`

        is human-readable; `instance` is a per-request identifier suitable for

        log correlation.

        '
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the problem type.
          example: https://docs.avaprotocol.org/errors/workflow-not-found
        title:
          type: string
          description: Short, human-readable summary.
          example: Workflow not found
        status:
          type: integer
          format: int32
          description: HTTP status code (echoed for clients that surface only the body).
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: No workflow with id 01JG2FE5MDVKBPHEG0PEYSDKAC for owner 0xabc...
        instance:
          type: string
          description: URI / opaque ID identifying this specific occurrence (e.g., request id).
          example: req_01JG2FE5MFKTH0754RGF2DMVY7
        code:
          type: string
          description: 'Machine-readable error code. Stable across releases; clients can

            switch on this for programmatic handling. Mirrors the gRPC-era

            ErrorCode enum vocabulary.

            '
          example: WORKFLOW_NOT_FOUND
    EventMethodCall:
      type: object
      required:
      - methodName
      properties:
        methodName:
          type: string
        callData:
          $ref: '#/components/schemas/Hex'
        applyToFields:
          type: array
          items:
            type: string
        methodParams:
          type: array
          items:
            type: string
            description: Handlebars template; resolves against decoded event data.
    FixedTimeTriggerConfig:
      type: object
      description: Fires at one or more absolute Unix-epoch milliseconds.
      required:
      - epochs
      properties:
        epochs:
          type: array
          items:
            type: integer
            format: int64
          minItems: 1
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequest:
      description: Request validation failed.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT bearer token. Obtained via `POST /auth:exchange` (wallet

        signature flow) or via the operator-run `create-api-key` CLI

        (long-lived, server-to-server). Send on every request as

        `Authorization: Bearer <jwt>`.

        '