openapi: 3.1.1
info:
  version: 0.1.0
  title: Understory API
  description: >
    This is the reference documentation for the Understory API.

    Here you can find detailed information about the API endpoints, request and
    response formats, and authentication methods.


    For more general information, go to [Documentation](/docs).


    {% partial file="/_partials/preview-admonition.md" /%}
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.understory.io
tags:
  - name: Booking
    description: >
      This is an early version of the Bookings API specification.


      Most of these APIs are available in production for testing.

      Endpoints marked as "Preview" are not yet available in production.


      Breaking changes might be introduced, but the overall specification is
      close to stable.
    x-displayName: Booking
  - name: Experience
    description: |
      This is a preview of the Experience API specification.

      The API is not yet available in production.
    x-displayName: Experience
  - name: Event
    description: |
      This is a preview of the Events API specification.

      The API is not yet available in production.
    x-displayName: Event
  - name: Grow
    description: This is a collection of endpoints related to Understory Grow.
    x-displayName: Grow
  - name: Test
    description: >
      These endpoints are for testing purposes only.


      You can use them to verify that your integration authentication works as
      intended.
    x-displayName: Test
paths:
  /v1/bookings:
    get:
      tags:
        - Booking
      summary: Get Bookings
      description: Get all bookings.
      operationId: getBookings
      x-badges:
        - name: Alpha
          color: '#c36760'
      x-hideReplay: true
      security:
        - OAuth2:
            - booking.read
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
          description: |
            The cursor for pagination.
            An empty string indicates the start of the list.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            format: int32
          description: The maximum number of bookings to return.
        - name: from
          in: query
          schema:
            type: string
            format: date-time
            description: Filter bookings made after the provided timestamp.
        - name: to
          in: query
          schema:
            type: string
            format: date-time
            description: Filter bookings made before the provided timestamp.
        - name: sort
          in: query
          schema:
            type: string
            default: '-created_at'
            description: >
              Field to define the sort order. To indicate sorting direction,
              fields may be prefixed with `+` (ascending) or `-` (descending).


              Ensure to URL escape the value as `+` can otherwise be interpreted
              as a space.


              Only fields `created_at` and `updated_at` are supported.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: |
                      The cursor for the next page.
                      An empty string indicates the end of the list.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Booking'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error.
            This will be 5XX error code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Booking
      summary: Create Booking
      description: Create a new booking for an event.
      operationId: createBooking
      x-badges:
        - name: Alpha
          color: '#c36760'
      x-hideReplay: true
      security:
        - OAuth2:
            - booking.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event_id
                - customer
                - locale
                - items
              properties:
                event_id:
                  type: string
                  description: The unique identifier of the event.
                customer:
                  oneOf:
                    - $ref: '#/components/schemas/CompanyCustomer'
                    - $ref: '#/components/schemas/PrivateCustomer'
                  description: The customer making the booking.
                locale:
                  type: string
                  description: >
                    Combination of language and country/region.

                    The format is a lowercase ISO 639-1 language code followed
                    by an optional hyphen and an

                    uppercase ISO 3166-1 country code.
                items:
                  type: array
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/Item'
                metadata:
                  type: object
                  description: >
                    Additional metadata for the booking.


                    This property lets you add custom data to the booking, e.g.
                    your own booking reference.

                    The key has a limit of 40 characters and the value has a
                    limit of 500 characters.
                  additionalProperties:
                    type: string
      responses:
        '201':
          description: Booking successfully created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - status
                properties:
                  id:
                    type: string
                    description: The unique identifier of the booking.
                  status:
                    $ref: '#/components/schemas/BookingStatus'
                    description: |
                      The status of the booking.

                      This will always be "ACTIVE" when the booking is created.
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Request violates a business rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error.
            This will be 5XX errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/bookings/{bookingId}:
    parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the booking.
    get:
      tags:
        - Booking
      summary: Get Booking
      description: Get a booking by its ID.
      operationId: getBooking
      x-badges:
        - name: Alpha
          color: '#c36760'
      x-hideReplay: true
      security:
        - OAuth2:
            - booking.read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error.
            This will be 5XX error code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/bookings/{bookingId}/tickets:
    parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the booking.
    get:
      tags:
        - Booking
      summary: Get Tickets
      description: Get all tickets for a booking.
      operationId: getTickets
      x-badges:
        - name: Alpha
          color: '#c36760'
      x-hideReplay: true
      security:
        - OAuth2:
            - booking.read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ticket'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error.
            This will be 5XX error code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/experiences/{experienceId}/information-requests:
    parameters:
      - schema:
          type: string
        name: experienceId
        description: The ID of the experience.
        in: path
        required: true
      - name: Accept-Language
        in: header
        schema:
          $ref: '#/components/schemas/AcceptLanguageHeader'
        required: true
      - name: cursor
        in: query
        schema:
          type: string
        description: |
          The cursor for pagination.
          An empty string indicates the start of the list.
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
          format: int32
        description: The maximum number of requests to return.
    get:
      tags:
        - Booking
        - Experience
      summary: Get information requests
      description: >
        Information requests describes additional information that is collected
        during the booking flow.


        These are usually presented as additional questions to be answered by
        the guest.
      operationId: getInformationRequestsForExperience
      security:
        - OAuth2:
            - experience.read
      x-badges:
        - name: Preview
          color: '#5a7f68'
      x-hideReplay: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: |
                      The cursor for the next page.
                      An empty string indicates the end of the list.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/InformationRequest'
  /v1/experiences/{experienceId}/ticket-variants:
    parameters:
      - schema:
          type: string
        name: experienceId
        description: The ID of the experience.
        in: path
        required: true
      - name: Accept-Language
        in: header
        schema:
          $ref: '#/components/schemas/AcceptLanguageHeader'
        required: true
      - name: cursor
        in: query
        schema:
          type: string
        description: |
          The cursor for pagination.
          An empty string indicates the start of the list.
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
          format: int32
        description: The maximum number of requests to return.
    get:
      tags:
        - Booking
        - Experience
      summary: Get ticket variants
      description: >
        Ticket variants describe the ticket options available for booking an
        experience.
      operationId: getTicketVariantsForExperience
      security:
        - OAuth2:
            - experience.read
      x-badges:
        - name: Preview
          color: '#5a7f68'
      x-hideReplay: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: |
                      The cursor for the next page.
                      An empty string indicates the end of the list.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TicketVariant'
  /v1/events:
    get:
      tags:
        - Event
      summary: Get events
      description: Get all events for the company.
      operationId: getEvents
      x-badges:
        - name: Preview
          color: '#5a7f68'
      x-hideReplay: true
      security:
        - OAuth2:
            - event.read
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
          description: |
            The cursor for pagination.
            An empty string indicates the start of the list.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            maximum: 1000
            minimum: 1
            format: int32
          description: The maximum number of events to return.
        - name: from
          in: query
          schema:
            type: string
            format: date-time
            description: Filter events based on the provided timestamp.
        - name: to
          in: query
          schema:
            type: string
            format: date-time
            description: Filter events based on the provided timestamp.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: |
                      The cursor for the next page.
                      An empty string indicates the end of the list.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
  /v1/events/{eventId}:
    get:
      tags:
        - Event
      summary: Get event
      description: Get an event by its ID.
      operationId: getEvent
      x-badges:
        - name: Preview
          color: '#5a7f68'
      x-hideReplay: true
      security:
        - OAuth2:
            - event.read
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the event.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/experiences:
    get:
      tags:
        - Experience
      summary: Get experiences
      description: Get all experiences for the company.
      operationId: getExperiences
      x-badges:
        - name: Preview
          color: '#5a7f68'
      x-hideReplay: true
      security:
        - OAuth2:
            - experience.read
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
          description: |
            The cursor for pagination.
            An empty string indicates the start of the list.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            format: int32
          description: The maximum number of experiences to return.
        - name: Accept-Language
          in: header
          schema:
            $ref: '#/components/schemas/AcceptLanguageHeader'
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: |
                      The cursor for the next page.
                      An empty string indicates the end of the list.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experience'
  /v1/experiences/{experienceId}:
    parameters:
      - schema:
          type: string
        name: experienceId
        in: path
        required: true
      - name: Accept-Language
        in: header
        schema:
          $ref: '#/components/schemas/AcceptLanguageHeader'
        required: true
    get:
      tags:
        - Experience
      summary: Get experience
      description: Get an experience by its ID.
      operationId: getExperienceById
      security:
        - OAuth2:
            - experience.read
      x-badges:
        - name: Preview
          color: '#5a7f68'
      x-hideReplay: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
  /v1/marketing-consents:
    get:
      tags:
        - Grow
      summary: Get marketing consents
      description: Get all marketing consents collected through Understory checkouts.
      operationId: getMarketingConsents
      security:
        - OAuth2:
            - marketing.read
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
          description: |
            The cursor for pagination.
            An empty string indicates the start of the list.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            format: int32
          description: The maximum number of marketing consents to return.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  next:
                    type: string
                    description: |
                      The cursor for the next page.
                      An empty string indicates the end of the list.
                  items:
                    description: The list of marketing consents.
                    type: array
                    items:
                      $ref: '#/components/schemas/MarketingConsent'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/me:
    get:
      tags:
        - Test
      summary: Who am I
      description: Get information about the current user.
      operationId: getMe
      security:
        - OAuth2: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 authentication using the client credentials flow
      flows:
        clientCredentials:
          tokenUrl: https://api.auth.understory.io/oauth2/token
          scopes: {}
        authorizationCode:
          authorizationUrl: https://api.auth.understory.io/oauth2/auth
          tokenUrl: https://api.auth.understory.io/oauth2/token
          scopes: {}
  schemas:
    Booking:
      type: object
      required:
        - id
        - status
        - created_at
        - updated_at
        - company_id
        - experience_id
        - event_id
        - customer
        - locale
      properties:
        id:
          type: string
          description: The unique identifier of the booking.
        status:
          $ref: '#/components/schemas/BookingStatus'
          description: The status of the booking.
        source:
          type: string
          description: The source of the booking.
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the booking was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the booking was last updated.
        company_id:
          type: string
          description: The ID of the company hosting the experience.
        experience_id:
          type: string
          description: The unique identifier of the experience.
        event_id:
          type: string
          description: The unique identifier of the event.
        locale:
          type: string
          description: >
            Combination of language and country/region.

            The format is a lowercase ISO 639-1 language code followed by an
            optional hyphen and an

            uppercase ISO 3166-1 country code.
        customer:
          description: The customer that made the booking.
          discriminator:
            propertyName: customer_type
            mapping:
              PRIVATE: '#/components/schemas/PrivateCustomer'
              COMPANY: '#/components/schemas/CompanyCustomer'
          oneOf:
            - $ref: '#/components/schemas/CompanyCustomer'
            - $ref: '#/components/schemas/PrivateCustomer'
        internal_note:
          $ref: '#/components/schemas/MarkdownText'
          description: Internal note for the booking.
        metadata:
          type: object
          description: >
            Additional metadata for the booking.


            This property lets you add custom data to the booking, e.g. your own
            booking reference.

            The key has a limit of 40 characters and the value has a limit of
            500 characters.
          additionalProperties:
            type: string
    BookingStatus:
      type: string
      enum:
        - ACTIVE
        - CANCELLED
        - MOVED
        - PROCESSING
        - CHECKED_IN
        - UNKNOWN
    PrivateCustomer:
      type: object
      required:
        - customer_type
        - full_name
        - email
        - phone
        - address
      properties:
        customer_type:
          $ref: '#/components/schemas/CustomerType'
          description: For private customers, this is always "PRIVATE"
        full_name:
          type: string
          description: The name of the customer.
        email:
          type: string
          format: email
          description: The email address of the customer.
        phone:
          type: string
          description: The phone number of the customer.
        address:
          $ref: '#/components/schemas/Address'
    CompanyCustomer:
      type: object
      required:
        - customer_type
        - company_name
        - vat_number
        - email
        - phone
        - address
      properties:
        customer_type:
          $ref: '#/components/schemas/CustomerType'
          description: For company customers, this is always "COMPANY"
        company_name:
          type: string
          description: The name of the company.
        vat_number:
          type: string
          description: The VAT number of the company.
        email:
          type: string
          format: email
          description: The email address of the customer.
        name:
          type: string
          description: The name of the customer.
        phone:
          type: string
          description: The phone number of the customer.
        address:
          $ref: '#/components/schemas/Address'
    CustomerType:
      type: string
      enum:
        - PRIVATE
        - COMPANY
    Address:
      type: object
      required:
        - address_lines
        - city
        - zip_code
        - country
      properties:
        address_lines:
          type: array
          minItems: 1
          maxItems: 2
          items:
            type: string
          description: >
            Address lines.

            The first line is the primary address line, e.g. street name and
            number.

            The second line is the secondary address line, e.g. apartment
            number.
        city:
          type: string
          description: The city of the customer.
        zip_code:
          type: string
          description: The postal code of the customer.
        region:
          type: string
          description: |
            The region of the customer.
            This can be a state, province, or other administrative region.
        country:
          type: string
          description: The country of the customer.
          format: iso-3166-1-alpha-2
    Ticket:
      type: object
      required:
        - id
        - urls
        - status
        - items
      properties:
        id:
          type: string
          description: The unique identifier of the ticket.
        status:
          type: string
          enum:
            - ACTIVE
            - VOIDED
            - CHECKED_IN
            - UNKNOWN
          description: The status of the ticket.
        urls:
          type: array
          description: The URLs associated with the ticket.
          minItems: 1
          items:
            type: object
            required:
              - type
              - url
            properties:
              type:
                type: string
                description: The type of the URL.
                enum:
                  - PDF
              url:
                type: string
                format: uri
                description: URL to the ticket.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
          description: The items associated with the ticket, e.g. variants or addons.
        check_in:
          type: object
          required:
            - check_in_time
            - checked_in_by
            - method
          properties:
            check_in_time:
              type: string
              format: date-time
              description: Timestamp of when the ticket was checked in.
            checked_in_by:
              type: string
              description: The ID of the person who checked in the ticket.
            method:
              type: string
              description: The method used to check in the ticket.
              enum:
                - MANUAL
                - QR_CODE_SCAN
                - UNKNOWN
    Item:
      type: object
      required:
        - type_id
        - item_type
        - quantity
      properties:
        type_id:
          type: string
          description: The unique identifier of the item type.
        item_type:
          type: string
          description: The type of item.
          enum:
            - VARIANT
            - ADDON
            - UNKNOWN
        quantity:
          type: integer
          minimum: 1
          description: The quantity of the item.
    InformationRequest:
      type: object
      required:
        - id
        - type
        - required
        - scope
        - label
      properties:
        id:
          type: string
        type:
          type: string
          description: >
            What type of response is expected from the guest.


            This will be extended in the future with additional types, eg.
            MULTI_CHOICE.
          enum:
            - TEXT
        required:
          type: boolean
          description: >-
            Indicates whether this information request is required to be
            answered.
        scope:
          description: >
            Defines at what scope this information is collected.


            If the scope is BOOKING, the information is collected once per
            booking, eg. "Something something".


            If the scope is TICKET, the information is collected for each ticket
            in the booking, eg. "What size of bicycle do you want?".
          enum:
            - BOOKING
            - TICKET
        label:
          type: string
          description: The display label for the information request.
    TicketVariant:
      type: object
      required:
        - id
        - name
        - price
        - vat_amount
      properties:
        id:
          type: string
          description: The unique identifier of the ticket variant.
        name:
          type: string
          description: The name of the ticket variant.
        description:
          type: string
          description: The description of the ticket variant.
        price:
          $ref: '#/components/schemas/PriceAmount'
          description: The price of the ticket variant.
        vat_amount:
          $ref: '#/components/schemas/PriceAmount'
          description: The VAT amount of the ticket variant.
        add_on_variants:
          type: array
          description: List of add-on variants that can be added to this ticket variant.
          items:
            $ref: '#/components/schemas/AddOnVariant'
    AddOnVariant:
      type: object
      required:
        - id
        - name
        - price
        - vat_amount
      properties:
        id:
          type: string
          description: The unique identifier of the add-on variant.
        name:
          type: string
          description: The name of the add-on variant.
        description:
          type: string
          description: The description of the add-on variant.
        price:
          $ref: '#/components/schemas/PriceAmount'
          description: The price of the add-on variant.
        vat_amount:
          $ref: '#/components/schemas/PriceAmount'
          description: The VAT amount of the add-on variant.
    PriceAmount:
      type: object
      required:
        - currency
        - value
        - exponent
      properties:
        currency:
          type: string
          description: The ISO 4217 currency code.
          example: USD
        value:
          type: integer
          description: The price in the smallest currency unit (e.g. cents for USD).
          example: 2500
        exponent:
          type: integer
          description: The number of decimal places for the currency.
          example: 2
    MarkdownText:
      type: string
      description: |
        Markdown formatted text.
        This is a string that contains markdown syntax.
    Error:
      type: object
      required:
        - message
        - code
      properties:
        code:
          type: string
        message:
          type: string
    AcceptLanguageHeader:
      type: string
      example: en-GB; q=1.0, en-US; q=0.8
      description: >
        Combination of language and country/region.

        The format is a lowercase ISO 639-1 language code followed by an
        optional hyphen and an

        uppercase ISO 3166-1 country code.


        If no value matches what is available in the host's Storefront, an error
        response is returned.


        You can optionally provide multiple language-country pairs with a
        priority, separated by commas based on [content
        negotation](https://en.wikipedia.org/wiki/Content_negotiation).
    Event:
      type: object
      required:
        - id
        - state
        - visibility
        - experience_id
        - capacity
        - sessions
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: The unique identifier for the event.
        state:
          type: string
          description: The state of the event.
          enum:
            - ACTIVE
            - INACTIVE
            - CANCELLED
            - COMPLETED
        visibility:
          type: string
          description: The visibility of the event.
          enum:
            - PUBLIC
            - PRIVATE
        experience_id:
          type: string
          description: The unique identifier for the experience.
        capacity:
          description: The capacity of the event.
          $ref: '#/components/schemas/Capacity'
        sessions:
          type: array
          description: The sessions for the event.
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/Session'
        created_at:
          type: string
          format: date-time
          description: The date and time when the event was created.
        updated_at:
          type: string
          format: date-time
          description: The date and time when the event was last updated.
        metadata:
          $ref: '#/components/schemas/Metadata'
          description: >-
            A set of key-value pairs that are attached to the event for storing
            additional information.
    Capacity:
      type: object
      required:
        - total
        - reserved
      properties:
        total:
          type: integer
          description: The total number of seats.
        reserved:
          type: integer
          description: The number of reserved seats.
    Session:
      type: object
      required:
        - id
        - start_time
        - end_time
        - timezone
        - location_id
        - languages
      properties:
        id:
          type: string
          description: The unique identifier for the session.
        start_time:
          type: string
          format: date-time
          description: The start time of the session.
        end_time:
          type: string
          format: date-time
          description: The end time of the session.
        timezone:
          type: string
          description: The IANA time zone name for the session.
          example: Europe/Copenhagen
        location_id:
          type: string
          description: The unique identifier for the location of the session.
        languages:
          type: array
          description: The languages spoken during the session.
          items:
            type: string
            format: iso-639-1
            example: en
    Metadata:
      type: object
      properties:
        example_key:
          type: string
          description: Example of a metadata key.
      additionalProperties: true
    Experience:
      type: object
      required:
        - id
        - type
        - state
        - name
        - created_at
        - updated_at
      properties:
        id:
          description: The unique identifier for the experience.
          type: string
        type:
          type: string
          description: The type of experience.
          enum:
            - MULTI_SESSION
            - SINGLE_SESSION
        state:
          type: string
          description: The state of the experience.
          enum:
            - ACTIVE
            - ARCHIVED
            - DELETED
        name:
          type: string
          description: The name of the experience.
        description:
          $ref: '#/components/schemas/MarkdownText'
          description: >
            A detailed description of the experience.


            The description is in markdown format, and can include rich text,
            links, and lists.
        tag_ids:
          type: array
          description: |
            Array of tag IDs that are associated with the experience.

            Tags can be used to categorize and filter experiences.
          items:
            type: string
        media:
          type: array
          description: Media attached to the experience.
          items:
            $ref: '#/components/schemas/Media'
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the experience was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the experience was last updated.
        metadata:
          $ref: '#/components/schemas/Metadata'
          description: >-
            A set of key-value pairs that are attached to the experience for
            storing additional information.
    Media:
      discriminator:
        propertyName: type
        mapping:
          IMAGE: '#/components/schemas/Image'
          VIDEO: '#/components/schemas/Video'
      oneOf:
        - $ref: '#/components/schemas/Image'
        - $ref: '#/components/schemas/Video'
    Image:
      type: object
      required:
        - type
        - url
        - mime_type
      properties:
        type:
          type: string
          enum:
            - IMAGE
        url:
          type: string
          format: uri
        mime_type:
          type: string
    Video:
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - VIDEO
        url:
          type: string
          format: uri
    MarketingConsent:
      type: object
      required:
        - company_id
        - full_name
        - email
        - source
      properties:
        company_id:
          type: string
          description: The company's unique ID.
        full_name:
          type: string
          description: The full name of the person who has given marketing consent.
        email:
          type: string
          description: The email of the person who has given marketing consent.
        source:
          type: string
          description: The source from which the consent was given.
    Me:
      type: object
      properties:
        company_id:
          type: string
          description: Your company's ID.
        company_name:
          type: string
          description: Your company's Name.
        user_id:
          type: string
          description: Your user ID.
        email:
          type: string
          description: Your email.
