Avetta Events API

openapi: 3.2.0
info:
  title: Avetta Events API
  version: '2026-05-08'
  license:
    name: Trade secret
    url: https://avetta.com
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: avetta-worker-v1.json, avetta-worker-v1-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{environment}.avetta.com/api/v1
  variables:
    environment:
      default: worker
      enum:
      - worker
      - au-worker
security:
- ApiKeyAuth: []
tags:
- name: Events
  description: The Events API allows you to list events.
paths:
  /events:
    get:
      operationId: getEvents
      tags:
      - Events
      summary: List of events
      description: Returns a list of events based on the user Reports permission, if the user is a worker, it will return the events that are applicable to the worker
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-typeParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/siteParam'
      - $ref: '#/components/parameters/parameters-showInactiveParam'
      responses:
        '200':
          $ref: '#/components/responses/successfulEvents'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/{id}:
    get:
      operationId: getEventsID
      tags:
      - Events
      summary: Get a single event
      description: Returns a single event by id, applying the same Reports-permission scoping as GET /events. If the id does not exist or is not visible to the caller, a 401 (Invalid security) response is returned instead of a 404 - the API does not distinguish "not found" from "not permitted". When user_id is also supplied, the response may include "review" and/or "history" (the user's pending / most recent accepted document review for this event), subject to the caller having Credit / Report security over that user.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-typeParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/siteParam'
      - $ref: '#/components/parameters/parameters-showInactiveParam'
      responses:
        '200':
          $ref: '#/components/responses/responses-successfulEvent'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/variances:
    get:
      operationId: getEventsVariances
      tags:
      - Events
      summary: List of events for variances
      description: Returns a list of events based on the Variances permission
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-typeParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/siteParam'
      - $ref: '#/components/parameters/parameters-showInactiveParam'
      responses:
        '200':
          $ref: '#/components/responses/successfulEvents'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/variances/{id}:
    get:
      operationId: getEventsVariancesID
      tags:
      - Events
      summary: Get a single event for variances
      description: Returns a single event by id, applying the same Variances-permission scoping as GET /events/variances. If the id does not exist or is not visible to the caller, a 401 (Invalid security) response is returned instead of a 404. When user_id is also supplied, the response may include "review" and/or "history", subject to the caller having Credit / Report security over that user.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-typeParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/siteParam'
      - $ref: '#/components/parameters/parameters-showInactiveParam'
      responses:
        '200':
          $ref: '#/components/responses/responses-successfulEvent'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/credits:
    get:
      operationId: getEventsCredits
      tags:
      - Events
      summary: List of events for credit
      description: Returns a list of events based on the Credit permission
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-typeParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/showAllParam'
      - $ref: '#/components/parameters/siteParam'
      - $ref: '#/components/parameters/parameters-showInactiveParam'
      responses:
        '200':
          $ref: '#/components/responses/successfulEvents'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/credits/{id}:
    get:
      operationId: getEventsCreditsID
      tags:
      - Events
      summary: Get a single event for credit
      description: Returns a single event by id, applying the same Credit-permission scoping as GET /events/credits. If the id does not exist or is not visible to the caller, a 401 (Invalid security) response is returned instead of a 404. When user_id is also supplied, the response may include "review" and/or "history", subject to the caller having Credit / Report security over that user.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-typeParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/showAllParam'
      - $ref: '#/components/parameters/siteParam'
      - $ref: '#/components/parameters/parameters-showInactiveParam'
      responses:
        '200':
          $ref: '#/components/responses/responses-successfulEvent'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/electives:
    get:
      operationId: getEventsElectives
      tags:
      - Events
      summary: List of elective events
      description: Returns a list of elective events available to the currently authenticated user (the elective attachment is always resolved against the calling session's user, not a user_id query parameter)
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/siteParam'
      responses:
        '200':
          $ref: '#/components/responses/successfulEvents'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
  /events/electives/{id}:
    get:
      operationId: getEventsElectivesID
      tags:
      - Events
      summary: Get a single elective event
      description: 'Returns a single elective event for the currently authenticated user. Note: unlike /events/{id}, /events/variances/{id} and /events/credits/{id}, the id here does NOT filter the underlying query - the electives list is not queried by event id at all, so this returns the first row of the caller''s elective list. If user_id is also supplied, the response may include "review" and/or "history" for that user on this event, subject to the caller having Credit / Report security over that user. If the caller has no electives at all, a 401 (Invalid security) response is returned instead of a 404.'
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/startParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/parameters-searchParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/parameters-extraParam'
      - $ref: '#/components/parameters/siteParam'
      responses:
        '200':
          $ref: '#/components/responses/responses-successfulEvent'
        '400':
          $ref: '#/components/responses/parameterNotRecognized'
        '401':
          $ref: '#/components/responses/errorSecurity'
    servers:
    - url: https://{environment}.avetta.com/api/v1
      variables:
        environment:
          default: worker
          enum:
          - worker
          - au-worker
components:
  parameters:
    parameters-extraParam:
      name: extra
      in: query
      description: 'Additional data to include for each event, combinable in one call as a comma separated list (e.g. extra=pre-req,items,electives). Allowed values: pre-req, items, electives.

        '
      required: false
      schema:
        type: string
    sortParam:
      name: sort
      in: query
      description: Name of field to sort by
      required: false
      schema:
        type: string
        enum:
        - id
        - code
        - title
        - group
    limitParam:
      name: limit
      in: query
      description: Maximum number of records to return
      required: false
      schema:
        type: integer
        default: 3000
    parameters-typeParam:
      name: type
      in: query
      description: List of event types contatenated by comma ( requirement,equivalency )
      required: false
      schema:
        type: string
        enum:
        - requirement
        - track
        - job
        - survey
        - equivalency
        - optin
    parameters-searchParam:
      name: search
      in: query
      description: Search term for the event title
      required: false
      schema:
        type: string
    showAllParam:
      name: showAll
      in: query
      description: 1 to show all events, 0 to show only the ones in use, 0 is the default. Only affects results for /events/credits(/{id}) - ignored on the other events routes.
      required: false
      schema:
        type: integer
        enum:
        - 0
        - 1
    idParam:
      name: id
      in: path
      description: references an id to reduce list down to 1 item
      required: false
      schema:
        type: integer
    userParam:
      name: user_id
      in: query
      description: 'Filters the list of events to show only those applicable to the user. When combined with a specific event id, also determines whose pending / historic document review is included in the response, as "review" and/or "history" (subject to the caller having Credit / Report security over that user). Has no filtering effect on /events/electives(/{id}), which is always scoped to the calling session''s own user.

        '
      required: false
      schema:
        type: integer
    parameters-showInactiveParam:
      name: showInactive
      in: query
      description: 1 to show inactive events, 0 to not show inactive events, 0 is the default
      required: false
      schema:
        type: integer
        enum:
        - 0
        - 1
    startParam:
      name: start
      in: query
      description: Offset of the first record to return
      required: false
      schema:
        type: integer
        default: 1
    siteParam:
      name: site
      in: query
      description: Filters viewing based on the site
      required: false
      schema:
        type: integer
  schemas:
    eventSummarySchema:
      type: object
      format: object
      description: Compact representation of an event used inside items / pre-req / electives
      properties:
        id:
          type: integer
          description: Event ID
          example: 1826
        code:
          type: string
          description: Event code
          example: UJH-124
        title:
          type: string
          description: Event title
          example: Safety Orientation - Module 2
        type:
          type: string
          description: Event type
          example: requirement
    documentFileSchema:
      type: object
      format: object
      properties:
        id:
          type: integer
          description: Document ID
          example: 98765
        name:
          type: string
          description: File name
          example: certificate.pdf
        size:
          type: integer
          description: File size in bytes
          example: 245760
        type:
          type: string
          description: Always "web"
          example: web
        url:
          type: string
          description: URL to view the file, empty string if the caller cannot view it
          example: https://worker.avetta.com/files/certificate.pdf
        is_secure:
          type: boolean
          description: Whether the file is stored securely
          example: false
    messageSchema:
      type: object
      format: object
      properties:
        message:
          type: string
          description: Message of the response
        status:
          type: string
          description: Status of the response
        success:
          type: boolean
          description: Flag to show if the transaccion was successful
          enum:
          - true
          - false
        code:
          type: integer
          description: Code of the response
        detail:
          type: string
          description: Detail of the response
    eventsSchema:
      type: object
      format: object
      properties:
        id:
          type: integer
          description: Event ID
          example: 1825
        code:
          type: string
          description: Event code
          example: UJH-123
        title:
          type: string
          description: Event title
          example: Safety Orientation
        description:
          type: string
          description: Event description
          example: Safety Orientation for all workers
        instructions:
          type: string
          description: Event instructions
          example: Please complete the safety orientation before starting work
        category:
          type: string
          description: Event category
          example: Safety
        sub-category:
          type: string
          description: Event sub-category
          example: Orientation
        delivery_type:
          type: string
          description: Event delivery type
          example: Online
        cost:
          type: string
          description: Event cost
          example: 0
        hours:
          type: string
          description: Event hours
          example: 1
        type:
          type: string
          description: Event type
          example: requirement
        status:
          type: string
          description: Event status
          example: Active
        account:
          type: object
          format: object
          properties:
            id:
              type: integer
              description: Account ID
              example: 12345
            con_id:
              type: string
              description: Account code
              example: 67890
            name:
              type: string
              description: Account name
              example: Avetta
        items:
          type: array
          description: Immediate child events of this container event. Only present when extra=items was requested.
          items:
            $ref: '#/components/schemas/eventSummarySchema'
        pre-req:
          type: array
          description: Direct/immediate prerequisite events, one level only (not recursive). Only present when extra=pre-req was requested.
          items:
            $ref: '#/components/schemas/eventSummarySchema'
        electives:
          type: array
          description: Events attached to this container event as electives. Only present when extra=electives was requested.
          items:
            $ref: '#/components/schemas/eventSummarySchema'
        review:
          $ref: '#/components/schemas/documentReviewSchema'
        history:
          $ref: '#/components/schemas/documentHistorySchema'
    statsSchema:
      type: object
      properties:
        command:
          type: string
          description: Command
          example: Auth
        version:
          type: string
          description: Version
          example: v1
        type:
          type: string
          description: Type
          example: token
        msg:
          type: string
          description: Message
          example: Good
        start:
          type: integer
          description: Start
          example: 1
        time:
          type: number
          description: Time in seconds to execute the command
          example: 0.71513
        limit:
          type: integer
          description: Limit of records to return
          example: 3000
        owner:
          type: integer
          description: Owner
          example: 1234567890
        count:
          type: integer
          description: Count of records returned
          example: 12
        records:
          type: integer
          description: Total records
          example: 12
      additionalProperties: true
    documentReviewSchema:
      type: object
      format: object
      description: 'Pending document review awaiting credit for the requested user_id. Only present on a single-event lookup (an id was supplied) when user_id is also supplied and the caller has Credit security over that user.

        '
      properties:
        username:
          type: string
          description: Full name of the worker the review belongs to
          example: Jane Smith
        submitted:
          type: string
          format: date-time
          description: Date the review was submitted
        files:
          type: array
          items:
            $ref: '#/components/schemas/documentFileSchema'
    documentHistorySchema:
      type: object
      format: object
      description: 'Most recent accepted (credited) document review for the requested user_id. Only present on a single-event lookup (an id was supplied) when user_id is also supplied and the caller has Report security over that user.

        '
      properties:
        username:
          type: string
          description: Full name of the worker the review belongs to
          example: Jane Smith
        credited:
          type: string
          format: date-time
          description: Date the review was credited/accepted
        approved_by:
          type: string
          description: Full name of the approver
          example: John Doe
        files:
          type: array
          items:
            $ref: '#/components/schemas/documentFileSchema'
  examples:
    errorSecurity:
      summary: Error security
      value:
        stats:
          command: Auth
          version: v1
          type: token
          msg: unauthorized
          start: 1
          time: 0.71513
          limit: 3000
          owner: 1234567890
          count: 0
          records: 0
        data:
          success: false
          code: 401
    parameterNotRecognized:
      summary: Parameter not recognized
      value:
        stats:
          command: Auth
          version: v1
          type: token
          start: 1
          time: 0.71513
          limit: 3000
          owner: 1234567890
          count: 0
          records: 0
        data:
          message: Malformed request syntax
          status: Bad Request
          success: false
          code: 400
  responses:
    responses-successfulEvent:
      description: Successful - single event (returned unwrapped, not inside an array, when an id is supplied)
      content:
        application/json:
          schema:
            type: object
            format: object
            properties:
              stats:
                $ref: '#/components/schemas/statsSchema'
              events:
                $ref: '#/components/schemas/eventsSchema'
    errorSecurity:
      description: Error while checking security
      content:
        application/json:
          schema:
            type: object
            format: object
            properties:
              stats:
                $ref: '#/components/schemas/statsSchema'
              data:
                $ref: '#/components/schemas/messageSchema'
          examples:
            errorSecurity:
              $ref: '#/components/examples/errorSecurity'
    successfulEvents:
      description: Successful
      content:
        application/json:
          schema:
            type: object
            format: object
            properties:
              stats:
                $ref: '#/components/schemas/statsSchema'
              events:
                type: array
                items:
                  $ref: '#/components/schemas/eventsSchema'
    parameterNotRecognized:
      description: Parameter not recognized
      content:
        application/json:
          schema:
            type: object
            format: object
            properties:
              stats:
                $ref: '#/components/schemas/statsSchema'
              data:
                $ref: '#/components/schemas/messageSchema'
          examples:
            parameterNotRecognized:
              $ref: '#/components/examples/parameterNotRecognized'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Provide your API key in the `Authorization` request header using the format `apikey <key>`, e.g. `Authorization: apikey <key>`. Requests missing this header will fail.

        '
x-refined-from:
- avetta-worker-v1.json
- avetta-worker-v1-openapi.yml
x-tagGroups:
- name: Compliance
  tags:
  - Authentication
  - Compliance
- name: Account
  tags:
  - Account
- name: Worksite Safety
  tags:
  - Worksite-Safety
- name: Deprecated Endpoints
  tags:
  - Deprecated Endpoints
  - Error Handling