> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertour.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List event definitions



## OpenAPI

````yaml /api-reference-v2/openapi.json get /v2/projects/{projectId}/event-definitions
openapi: 3.0.0
info:
  title: Usertour API v2
  description: >-
    Project-scoped v2 API. Authenticate with a personal API token — an opaque
    `utp_...` string (NOT a JWT: do not try to decode it), created in the
    Usertour app under Settings → API, sent as `Authorization: Bearer utp_...`.
  version: '2.0'
  contact: {}
servers:
  - url: https://api.usertour.io
security: []
tags: []
paths:
  /v2/projects/{projectId}/event-definitions:
    get:
      tags:
        - Event definitions
      summary: List event definitions
      operationId: ApiEventDefinitionsController_list
      parameters:
        - name: projectId
          required: true
          in: path
          description: Project ID
          schema:
            type: string
        - name: cursor
          required: false
          in: query
          description: >-
            Opaque page cursor — the `cursor` query value found inside a prior
            response's `next`/`previous` URL. Normally you never build this
            yourself: just GET those URLs as-is.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: Max items per page (1-100, default 20).
          schema:
            minimum: 1
            maximum: 100
            default: 20
            type: integer
        - name: name
          required: false
          in: query
          description: Filter by name (case-insensitive substring match).
          schema:
            type: string
        - name: orderBy
          required: false
          in: query
          description: >-
            Order by createdAt / codeName / displayName (prefix - for
            descending). Text sorting is case-sensitive (byte order): uppercase
            sorts before lowercase.
          schema:
            anyOf:
              - type: string
                enum:
                  - createdAt
                  - '-createdAt'
                  - codeName
                  - '-codeName'
                  - displayName
                  - '-displayName'
              - type: array
                items:
                  type: string
                  enum:
                    - createdAt
                    - '-createdAt'
                    - codeName
                    - '-codeName'
                    - displayName
                    - '-displayName'
      responses:
        '200':
          description: List of event definitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventDefinitionsResponseDto'
        '400':
          description: >-
            Invalid request — E1017 validation (may carry `issues`; an invalid
            orderBy/limit is also E1017), E1015 invalid scope, E0003 invalid
            against current domain state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Missing or expired API key — E1010, E1020.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: >-
            Refused — E1000 invalid key, E1011 project not in token scope, E1012
            insufficient scope, E1029 environment not in token scope, E1032
            environment creation needs a token without env-targeted capabilities
            (its allowlist cannot cover a not-yet-existing environment).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            Rate limit exceeded — E1013. The limit follows the project's plan
            (100/500/1000/3000 requests per minute); unknown credentials share a
            per-IP bucket. Every response also carries X-RateLimit-Limit /
            -Remaining / -Reset for pacing; a 429 adds the standard Retry-After
            header (seconds to back off).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      security:
        - bearer: []
components:
  schemas:
    ListEventDefinitionsResponseDto:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              object:
                type: string
                enum:
                  - eventDefinition
              createdAt:
                type: string
                format: date-time
              description:
                type: string
              displayName:
                type: string
              codeName:
                type: string
              predefined:
                type: boolean
                description: >-
                  true = a built-in Usertour lifecycle event
                  (flow/launcher/checklist/survey/… started/ended/etc.) — NOT
                  trackable: a tracker can only fire a CUSTOM event. false = a
                  custom event you created.
              attributes:
                type: array
                items:
                  type: string
                description: >-
                  codeNames of the event-scoped attributes attached to this
                  event.
            required:
              - id
              - object
              - createdAt
              - description
              - displayName
              - codeName
              - predefined
              - attributes
        next:
          type: string
          description: >-
            Full URL of the next page — request it as-is (it already carries
            `cursor=` and your query parameters). null = no further pages.
          nullable: true
        previous:
          type: string
          description: >-
            Full URL of the previous page — request it as-is. null = already at
            the first page.
          nullable: true
      required:
        - results
        - next
        - previous
    ErrorResponseDto:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable machine-readable code (e.g. E1017). Match on this, never
                on `message`.
            message:
              type: string
              description: Human-readable summary. Wording may change between releases.
            issues:
              description: >-
                Validation errors (E1017) may carry one entry per problem so
                every field can be fixed in a single round-trip. Absent on other
                errors.
              type: array
              items:
                type: object
                properties:
                  rule:
                    type: string
                    description: >-
                      Which validation layer rejected it: schema |
                      reactive_condition | action_not_allowed | step_shape |
                      reference_target | auto_start | media_url. New values may
                      be added; treat an unknown value as a generic validation
                      failure.
                  message:
                    type: string
                  path:
                    description: >-
                      Path into the request body (e.g.
                      `steps[0].triggers[0].when[1]`).
                    type: string
                required:
                  - rule
                  - message
            doc_url:
              type: string
              description: Base URL of the API documentation.
      required:
        - error
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: utp_... personal API token (opaque)
      type: http

````