Hatchet Event API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Hatchet API Token Event API
  description: The Hatchet API
servers:
- url: ''
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: Event
paths:
  /api/v1/stable/tenants/{tenant}/events:
    get:
      x-resources:
      - tenant
      description: Lists all events for a tenant.
      operationId: v1-event:list
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      - description: The number to skip
        in: query
        name: offset
        required: false
        schema:
          type: integer
          format: int64
      - description: The number to limit by
        in: query
        name: limit
        required: false
        schema:
          type: integer
          format: int64
      - description: A list of keys to filter by
        in: query
        name: keys
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EventKey'
      - description: Consider events that occurred after this time
        in: query
        name: since
        schema:
          type: string
          format: date-time
      - description: Consider events that occurred before this time
        in: query
        name: until
        schema:
          type: string
          format: date-time
      - description: Filter to events that are associated with a specific workflow run
        in: query
        name: workflowIds
        schema:
          type: array
          items:
            type: string
            format: uuid
            minLength: 36
            maxLength: 36
      - description: Filter to events that are associated with workflow runs matching a certain status
        in: query
        name: workflowRunStatuses
        schema:
          type: array
          items:
            $ref: '#/components/schemas/V1TaskStatus'
      - description: Filter to specific events by their ids
        in: query
        name: eventIds
        schema:
          type: array
          items:
            type: string
            format: uuid
            minLength: 36
            maxLength: 36
      - description: Filter by additional metadata on the events
        in: query
        name: additionalMetadata
        schema:
          type: array
          items:
            type: string
            description: The metadata key-value pairs (delimited by a `:`) to filter by
            minLength: 1
      - description: The scopes to filter by
        in: query
        name: scopes
        schema:
          type: array
          items:
            type: string
            description: The scope to filter by
            minLength: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1EventList'
          description: Successfully listed the events
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: List Events
      tags:
      - Event
  /api/v1/stable/tenants/{tenant}/events/{v1-event}:
    get:
      x-resources:
      - tenant
      - v1-event
      description: Get an event by its id
      operationId: v1-event:get
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      - description: The event id
        in: path
        name: v1-event
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Event'
          description: Successfully listed the events
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: Get Events
      tags:
      - Event
  /api/v1/stable/tenants/{tenant}/events/keys:
    get:
      x-resources:
      - tenant
      description: Lists all event keys for a tenant.
      operationId: v1:event-key:list
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventKeyList'
          description: Successfully listed the event keys
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: List Event Keys
      tags:
      - Event
  /api/v1/tenants/{tenant}/events:
    get:
      x-resources:
      - tenant
      description: Lists all events for a tenant.
      operationId: event:list
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      - description: The number to skip
        in: query
        name: offset
        required: false
        schema:
          type: integer
          format: int64
      - description: The number to limit by
        in: query
        name: limit
        required: false
        schema:
          type: integer
          format: int64
      - description: A list of keys to filter by
        in: query
        name: keys
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EventKey'
      - description: A list of workflow IDs to filter by
        in: query
        name: workflows
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowID'
      - description: A list of workflow run statuses to filter by
        in: query
        name: statuses
        required: false
        schema:
          $ref: '#/components/schemas/WorkflowRunStatusList'
      - description: The search query to filter for
        in: query
        name: search
        required: false
        schema:
          $ref: '#/components/schemas/EventSearch'
      - description: What to order by
        in: query
        name: orderByField
        required: false
        schema:
          $ref: '#/components/schemas/EventOrderByField'
      - description: The order direction
        in: query
        name: orderByDirection
        required: false
        schema:
          $ref: '#/components/schemas/EventOrderByDirection'
      - description: A list of metadata key value pairs to filter by
        in: query
        name: additionalMetadata
        example:
        - key1:value1
        - key2:value2
        required: false
        schema:
          type: array
          items:
            type: string
      - description: A list of event ids to filter by
        in: query
        name: eventIds
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
            minLength: 36
            maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
          description: Successfully listed the events
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: List Events
      tags:
      - Event
    post:
      x-resources:
      - tenant
      description: Creates a new event.
      operationId: event:create
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
        description: The event to create
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
          description: Successfully created the event
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Resource limit exceeded
      summary: Create Event
      tags:
      - Event
  /api/v1/tenants/{tenant}/events/bulk:
    post:
      x-resources:
      - tenant
      description: Bulk creates new events.
      operationId: event:create:bulk
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCreateEventRequest'
        description: The events to create
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events'
          description: Successfully created the events
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Resource limit exceeded
      summary: Bulk Create Events
      tags:
      - Event
  /api/v1/tenants/{tenant}/events/replay:
    post:
      x-resources:
      - tenant
      description: Replays a list of events.
      operationId: event:update:replay
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayEventRequest'
        description: The event ids to replay
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
          description: Successfully replayed the events
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Resource limit exceeded
      summary: Replay Events
      tags:
      - Event
  /api/v1/tenants/{tenant}/events/cancel:
    post:
      x-resources:
      - tenant
      description: Cancels all runs for a list of events.
      operationId: event:update:cancel
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelEventRequest'
        description: The event ids to replay
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflowRunIds:
                    type: array
                    items:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
          description: Successfully canceled runs for the events
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Resource limit exceeded
      summary: Replay Events
      tags:
      - Event
  /api/v1/events/{event}:
    get:
      x-resources:
      - tenant
      - event
      description: Get an event.
      operationId: event:get
      parameters:
      - description: The event id
        in: path
        name: event
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
          description: Successfully retrieved the event data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: Get Event Data
      tags:
      - Event
  /api/v1/events/{event}/data:
    get:
      x-resources:
      - tenant
      - event
      description: Get the data for an event.
      operationId: event-data:get
      parameters:
      - description: The event id
        in: path
        name: event
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventData'
          description: Successfully retrieved the event data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: Get Event Data
      tags:
      - Event
  /api/v1/tenants/{tenant}/events/{event-with-tenant}/data:
    get:
      x-resources:
      - tenant
      - event-with-tenant
      description: Get the data for an event.
      operationId: event-data:get-with-tenant
      parameters:
      - description: The event id
        in: path
        name: event-with-tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventData'
          description: Successfully retrieved the event data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: Get Event Data
      tags:
      - Event
  /api/v1/tenants/{tenant}/events/keys:
    get:
      x-resources:
      - tenant
      description: Lists all event keys for a tenant.
      operationId: event-key:list
      parameters:
      - description: The tenant id
        in: path
        name: tenant
        required: true
        schema:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventKeyList'
          description: Successfully listed the event keys
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: A malformed or bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrors'
          description: Forbidden
      summary: List Event Keys
      tags:
      - Event
components:
  schemas:
    EventData:
      properties:
        data:
          type: string
          description: The data for the event (JSON bytes).
      required:
      - data
    TenantEnvironment:
      enum:
      - local
      - development
      - production
      type: string
    EventKey:
      type: string
      description: The key for the event.
    Tenant:
      properties:
        metadata:
          $ref: '#/components/schemas/APIResourceMeta'
        name:
          type: string
          description: The name of the tenant.
        slug:
          type: string
          description: The slug of the tenant.
        analyticsOptOut:
          type: boolean
          description: Whether the tenant has opted out of analytics.
        alertMemberEmails:
          type: boolean
          description: Whether to alert tenant members.
        version:
          $ref: '#/components/schemas/TenantVersion'
          description: The version of the tenant.
        environment:
          $ref: '#/components/schemas/TenantEnvironment'
          description: The environment type of the tenant.
        serverUrl:
          type: string
          description: The server URL for the tenant (includes scheme)
        region:
          type: string
          description: Control-plane shard region for the tenant (e.g. aws:us-west-2).
      required:
      - metadata
      - name
      - slug
      - version
      type: object
    APIResourceMeta:
      type: object
      properties:
        id:
          type: string
          description: the id of this resource, in UUID format
          example: bb214807-246e-43a5-a25d-41761d1cff9e
          minLength: 0
          maxLength: 36
        createdAt:
          type: string
          description: the time that this resource was created
          format: date-time
          example: '2022-12-13T15:06:48.888358-05:00'
        updatedAt:
          type: string
          description: the time that this resource was last updated
          format: date-time
          example: '2022-12-13T15:06:48.888358-05:00'
      required:
      - id
      - createdAt
      - updatedAt
    APIError:
      type: object
      properties:
        code:
          type: integer
          description: a custom Hatchet error code
          format: uint64
          example: 1400
        field:
          type: string
          description: the field that this error is associated with, if applicable
          example: name
        description:
          type: string
          description: a description for this error
          example: A descriptive error message
        docs_link:
          type: string
          description: a link to the documentation for this error, if it exists
          example: github.com/hatchet-dev/hatchet
      required:
      - description
    CreateEventRequest:
      properties:
        key:
          type: string
          description: The key for the event.
        data:
          type: object
          description: The data for the event.
        additionalMetadata:
          type: object
          description: Additional metadata for the event.
        priority:
          type: integer
          description: The priority of the event.
          format: int32
        scope:
          type: string
          description: The scope for event filtering.
      required:
      - key
      - data
    PaginationResponse:
      type: object
      properties:
        current_page:
          type: integer
          description: the current page
          format: int64
          example: 2
        next_page:
          type: integer
          description: the next page
          format: int64
          example: 3
        num_pages:
          type: integer
          description: the total number of pages for listing
          format: int64
          example: 10
      example:
        next_page: 3
        num_pages: 10
        current_page: 2
    CancelEventRequest:
      properties:
        eventIds:
          type: array
          items:
            type: string
            example: bb214807-246e-43a5-a25d-41761d1cff9e
            minLength: 36
            maxLength: 36
            format: uuid
      required:
      - eventIds
    Event:
      properties:
        metadata:
          $ref: '#/components/schemas/APIResourceMeta'
        key:
          type: string
          description: The key for the event.
        tenant:
          $ref: '#/components/schemas/Tenant'
          description: The tenant associated with this event.
        tenantId:
          type: string
          description: The ID of the tenant associated with this event.
        workflowRunSummary:
          $ref: '#/components/schemas/EventWorkflowRunSummary'
          description: The workflow run summary for this event.
        additionalMetadata:
          type: object
          description: Additional metadata for the event.
      required:
      - metadata
      - key
      - tenantId
    BulkCreateEventRequest:
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CreateEventRequest'
      required:
      - events
    V1Event:
      properties:
        metadata:
          $ref: '#/components/schemas/APIResourceMeta'
        key:
          type: string
          description: The key for the event.
        tenant:
          $ref: '#/components/schemas/Tenant'
          description: The tenant associated with this event.
        tenantId:
          type: string
          description: The ID of the tenant associated with this event.
        workflowRunSummary:
          $ref: '#/components/schemas/V1EventWorkflowRunSummary'
          description: The workflow run summary for this event.
        additionalMetadata:
          type: object
          description: Additional metadata for the event.
        payload:
          type: object
          description: The payload of the event, which can be any JSON-serializable object.
        scope:
          type: string
          description: The scope of the event, which can be used to filter or categorize events.
        seenAt:
          type: string
          format: date-time
          description: The timestamp when the event was seen.
        triggeredRuns:
          description: The external IDs of the runs that were triggered by this event.
          type: array
          items:
            $ref: '#/components/schemas/V1EventTriggeredRun'
        triggeringWebhookName:
          type: string
          description: The name of the webhook that triggered this event, if applicable.
      required:
      - metadata
      - key
      - tenantId
      - workflowRunSummary
    Events:
      properties:
        metadata:
          $ref: '#/components/schemas/APIResourceMeta'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: The events.
      required:
      - metadata
      - events
    ReplayEventRequest:
      properties:
        eventIds:
          type: array
          items:
            type: string
            example: bb214807-246e-43a5-a25d-41761d1cff9e
            minLength: 36
            maxLength: 36
            format: uuid
      required:
      - eventIds
    EventList:
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        rows:
          items:
            $ref: '#/components/schemas/Event'
          type: array
    WorkflowRunStatusList:
      type: array
      items:
        $ref: '#/components/schemas/WorkflowRunStatus'
    EventSearch:
      type: string
    APIErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/APIError'
      required:
      - errors
    WorkflowID:
      type: string
      description: A workflow ID.
    TenantVersion:
      enum:
      - V0
      - V1
      type: string
    EventOrderByDirection:
      type: string
      enum:
      - asc
      - desc
    V1EventWorkflowRunSummary:
      properties:
        running:
          type: integer
          format: int64
          description: The number of running runs.
        queued:
          type: integer
          format: int64
          description: The number of queued runs.
        succeeded:
          type: integer
          format: int64
          description: The number of succeeded runs.
        failed:
          type: integer
          format: int64
          description: The number of failed runs.
        cancelled:
          type: integer
          format: int64
          description: The number of cancelled runs.
      required:
      - running
      - queued
      - succeeded
      - failed
      - cancelled
    WorkflowRunStatus:
      type: string
      enum:
      - PENDING
      - RUNNING
      - SUCCEEDED
      - FAILED
      - CANCELLED
      - QUEUED
      - BACKOFF
    V1EventTriggeredRun:
      type: object
      properties:
        workflowRunId:
          type: string
          format: uuid
          description: The external ID of the triggered run.
          minLength: 36
          maxLength: 36
        filterId:
          type: string
          format: uuid
          description: The ID of the filter that triggered the run, if applicable.
      required:
      - workflowRunId
    V1EventList:
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        rows:
          items:
            $ref: '#/components/schemas/V1Event'
          type: array
    EventOrderByField:
      type: string
      enum:
      - createdAt
    EventWorkflowRunSummary:
      properties:
        pending:
          type: integer
          format: int64
          description: The number of pending runs.
        running:
          type: integer
          format: int64
          description: The number of running runs.
        queued:
          type: integer
          format: int64
          description: The number of queued runs.
        succeeded:
          type: integer
          format: int64
          description: The number of succeeded runs.
        failed:
          type: integer
          format: int64
          description: The number of failed runs.
        cancelled:
          type: integer
          format: int64
          description: The number of cancelled runs.
    V1TaskStatus:
      type: string
      enum:
      - QUEUED
      - RUNNING
      - COMPLETED
      - CANCELLED
      - FAILED
    EventKeyList:
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        rows:
          items:
            $ref: '#/components/schemas/EventKey'
          type: array
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    cookieAuth:
      type: apiKey
      in: cookie
      name: hatchet
    customAuth:
      type: http
      scheme: bearer