openapi: 3.1.0
info:
  title: VATSIM AIP Airport info Events API
  version: 2.0.0
  termsOfService: https://vatsim.net/docs/policy/user-agreement
  contact:
    email: tech@vatsim.net
    name: VATSIM Technology Team
servers:
- url: https://my.vatsim.net/api/v2/aip
tags:
- name: Events
paths:
  /{num}:
    get:
      tags:
      - Events
      summary: List events
      description: Returns a list of the next {num} current and upcoming events.
      operationId: listEvents
      parameters:
      - name: num
        in: path
        description: Number of events to return, or 'all' to return all events
        schema:
          type:
          - integer
          - string
        example: 50
      responses:
        '200':
          $ref: '#/components/responses/ListEventsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
  /{num}/{regionId}:
    get:
      tags:
      - Events
      summary: List events by region
      description: Returns a list of the next {num} current and upcoming events in the specified region.
      operationId: listEventsByRegion
      parameters:
      - name: num
        in: path
        description: Number of events to return, or 'all' to return all events
        schema:
          type:
          - integer
          - string
        example: 50
      - name: regionId
        in: path
        description: Region ID to filter events by
        schema:
          type: string
        example: AMAS
      responses:
        '200':
          $ref: '#/components/responses/ListEventsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
components:
  responses:
    BadRequestResponse:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error message
                example: Unable to process the request.
    ListEventsResponse:
      description: Successful operation
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
  schemas:
    Event:
      type: object
      properties:
        id:
          type: integer
          description: Event ID
          example: 1
        type:
          type: string
          description: Event type
          example: Event
          enum:
          - Event
          - Controller Examination
          - VASOPS Event
        name:
          type: string
          description: Event name
          example: Example Event
        link:
          type: string
          description: Event link
          example: https://my.vatsim.net/events/example-event
        organisers:
          type: array
          description: Event organisers
          items:
            $ref: '#/components/schemas/Organiser'
        airports:
          type: array
          description: Event airports
          items:
            $ref: '#/components/schemas/Airport'
        routes:
          type: array
          description: Event routes
          items:
            $ref: '#/components/schemas/FlightPlan'
        start_time:
          type: string
          format: date-time
          description: Event start time
          example: 1970-01-01 00:00:00+00:00
        end_time:
          type: string
          format: date-time
          description: Event end time
          example: 1970-01-01 06:00:00+00:00
        short_description:
          type: string
          description: Event short description (HTML)
          example: <p>Fly with us tonight!</p>
        description:
          type: string
          description: Event description (HTML)
          example: <p>Fly with us tonight!</p>
        banner:
          type: string
          description: Event banner
          example: https://vatsim-my.nyc3.digitaloceanspaces.com/events/JpjoYKp6CRcz4V1wvdlMnQHiAtYOmT2p3DevEA7j.png
    Organiser:
      type: object
      properties:
        region:
          type:
          - string
          - 'null'
          description: Region ID
          example: AMAS
        division:
          type:
          - string
          - 'null'
          description: Division ID
          example: USA
        subdivision:
          type:
          - string
          - 'null'
          description: Subdivision ID
          example: null
        organised_by_vatsim:
          type: boolean
          description: Whether the event is organised by VATSIM
          example: false
    FlightPlan:
      type: object
      properties:
        departure:
          type: string
          description: Departure airport ICAO code
          example: KJFK
        arrival:
          type: string
          description: Arrival airport ICAO code
          example: KATL
        route:
          type: string
          description: Route
          example: RBV Q430 BYRDD J48 MOL FLASK OZZZI1
    Airport:
      type: object
      properties:
        icao:
          type: string
          description: Airport ICAO code
          example: KJFK