openapi: 3.1.0
info:
  title: Airbnb Activities API
  description: >-
    The Airbnb Activities API allows approved partners to integrate with
    Airbnb Experiences, the platform's marketplace for hosted activities and
    tours. It provides endpoints for managing experience listings, handling
    bookings, and synchronizing availability for activities offered by local
    hosts. Partners can use the API to build integrations that help experience
    hosts manage their offerings alongside other tour and activity platforms,
    enabling centralized management of schedules, pricing, and guest
    communications.
  version: '2025.03.31'
  contact:
    name: Airbnb Developer Support
    url: https://developer.withairbnb.com/
  termsOfService: https://www.airbnb.com/terms
externalDocs:
  description: Airbnb Developer Documentation
  url: https://developer.withairbnb.com/
servers:
- url: https://api.airbnb.com/v2
  description: Airbnb Production API Server
tags:
- name: Bookings
  description: >-
    Operations for managing guest bookings for experiences, including
    confirmations, cancellations, and attendee details.
- name: Experience Messages
  description: >-
    Operations for sending and retrieving messages between experience
    hosts and booked guests.
- name: Experiences
  description: >-
    Operations for creating, reading, updating, and managing experience
    and activity listings on Airbnb.
- name: Schedules
  description: >-
    Operations for managing experience schedules, time slots, and
    availability for hosted activities.
security:
- oauth2: []
paths:
  /experiences:
    get:
      operationId: listExperiences
      summary: List All Experiences
      description: >-
        Retrieves a paginated list of all experience listings managed by
        the authenticated partner. Supports filtering by status and
        activity category.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: status
        in: query
        description: >-
          Filter experiences by their current status on the platform.
        schema:
          type: string
          enum:
          - active
          - inactive
          - pending
          - suspended
      - name: category
        in: query
        description: >-
          Filter experiences by activity category.
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of experiences.
          content:
            application/json:
              schema:
                type: object
                properties:
                  experiences:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experience'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
    post:
      operationId: createExperience
      summary: Create a New Experience
      description: >-
        Creates a new experience listing on Airbnb with the provided
        details including activity type, location, description, pricing,
        and scheduling information. The experience will be in a pending
        state until reviewed and approved by Airbnb.
      tags:
      - Experiences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperienceCreate'
      responses:
        '201':
          description: The experience was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '400':
          description: The request body contains invalid or missing fields.
        '401':
          description: Authentication credentials are missing or invalid.
  /experiences/{experience_id}:
    get:
      operationId: getExperience
      summary: Get an Experience
      description: >-
        Retrieves the full details of a specific experience listing by
        its unique identifier, including description, schedule, pricing,
        and host information.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      responses:
        '200':
          description: The experience details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience was not found.
    put:
      operationId: updateExperience
      summary: Update an Experience
      description: >-
        Updates an existing experience listing with the provided fields.
        Only the fields included in the request body will be modified.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperienceUpdate'
      responses:
        '200':
          description: The experience was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '400':
          description: The request body contains invalid or missing fields.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience was not found.
    delete:
      operationId: deleteExperience
      summary: Delete an Experience
      description: >-
        Removes an experience listing from the Airbnb platform. Active
        bookings must be resolved before an experience can be deleted.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      responses:
        '204':
          description: The experience was successfully deleted.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience was not found.
        '409':
          description: The experience has active bookings and cannot be deleted.
  /experiences/{experience_id}/schedules:
    get:
      operationId: listExperienceSchedules
      summary: List Experience Schedules
      description: >-
        Retrieves the available time slots and schedule entries for a
        specific experience over a date range.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      - name: start_date
        in: query
        required: true
        description: >-
          The start date for the schedule range in ISO 8601 format.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        required: true
        description: >-
          The end date for the schedule range in ISO 8601 format.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: The schedule entries for the specified date range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schedules:
                    type: array
                    items:
                      $ref: '#/components/schemas/Schedule'
        '400':
          description: The date range is invalid or missing.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience was not found.
    post:
      operationId: createExperienceSchedule
      summary: Create an Experience Schedule
      description: >-
        Creates a new scheduled time slot for an experience, specifying
        the date, start time, and maximum number of attendees.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleCreate'
      responses:
        '201':
          description: The schedule was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '400':
          description: The request body contains invalid or missing fields.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience was not found.
  /experiences/{experience_id}/schedules/{schedule_id}:
    put:
      operationId: updateExperienceSchedule
      summary: Update an Experience Schedule
      description: >-
        Updates an existing schedule entry for an experience, allowing
        changes to time, capacity, or cancellation of the time slot.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      - $ref: '#/components/parameters/scheduleIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleUpdate'
      responses:
        '200':
          description: The schedule was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '400':
          description: The request body contains invalid or missing fields.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience or schedule was not found.
    delete:
      operationId: deleteExperienceSchedule
      summary: Delete an Experience Schedule
      description: >-
        Removes a scheduled time slot from an experience. Existing
        bookings for the time slot must be handled before deletion.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/experienceIdParam'
      - $ref: '#/components/parameters/scheduleIdParam'
      responses:
        '204':
          description: The schedule was successfully deleted.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The experience or schedule was not found.
        '409':
          description: The schedule has active bookings and cannot be deleted.
  /bookings:
    get:
      operationId: listBookings
      summary: List Experience Bookings
      description: >-
        Retrieves a paginated list of bookings for experiences managed
        by the authenticated partner. Supports filtering by status,
        experience, and date range.
      tags:
      - Bookings
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: status
        in: query
        description: >-
          Filter bookings by their current status.
        schema:
          type: string
          enum:
          - pending
          - confirmed
          - cancelled
          - completed
      - name: experience_id
        in: query
        description: >-
          Filter bookings by experience identifier.
        schema:
          type: string
      - name: start_date
        in: query
        description: >-
          Filter bookings with activity dates on or after this date.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: >-
          Filter bookings with activity dates on or before this date.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A paginated list of bookings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bookings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Booking'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
  /bookings/{booking_id}:
    get:
      operationId: getBooking
      summary: Get a Booking
      description: >-
        Retrieves the full details of a specific experience booking
        including attendee information, schedule, and pricing.
      tags:
      - Bookings
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      responses:
        '200':
          description: The booking details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking was not found.
  /bookings/{booking_id}/confirm:
    post:
      operationId: confirmBooking
      summary: Confirm a Booking
      description: >-
        Confirms a pending booking request for an experience. Once
        confirmed, the attendee count is updated on the schedule.
      tags:
      - Bookings
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      responses:
        '200':
          description: The booking was successfully confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking was not found.
        '409':
          description: The booking is not in a pending state.
  /bookings/{booking_id}/cancel:
    post:
      operationId: cancelBooking
      summary: Cancel a Booking
      description: >-
        Cancels an existing booking. Cancellation policies and refund
        rules may apply depending on timing and experience configuration.
      tags:
      - Bookings
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: >-
                    The reason for cancelling the booking.
      responses:
        '200':
          description: The booking was successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking was not found.
        '409':
          description: The booking cannot be cancelled in its current state.
  /bookings/{booking_id}/messages:
    get:
      operationId: listBookingMessages
      summary: List Booking Messages
      description: >-
        Retrieves the message thread for a specific booking, including
        all messages exchanged between the host and guest.
      tags:
      - Experience Messages
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A paginated list of messages in the booking thread.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExperienceMessage'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking was not found.
    post:
      operationId: sendBookingMessage
      summary: Send a Booking Message
      description: >-
        Sends a new message in the booking thread from the host to
        the guest regarding the experience booking.
      tags:
      - Experience Messages
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                  description: >-
                    The text content of the message to send.
                  maxLength: 5000
      responses:
        '201':
          description: The message was successfully sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceMessage'
        '400':
          description: The message content is invalid or exceeds length limits.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking was not found.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        Airbnb uses OAuth 2.0 for authentication. Partners must register
        their application to receive a client ID and secret, then obtain
        access tokens through the authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://www.airbnb.com/oauth2/auth
          tokenUrl: https://api.airbnb.com/v2/oauth2/authorizations
          scopes:
            experiences:read: Read experience information
            experiences:write: Create and update experiences
            bookings:read: Read booking information
            bookings:write: Confirm and cancel bookings
            messages:read: Read booking messages
            messages:write: Send messages to guests
  parameters:
    experienceIdParam:
      name: experience_id
      in: path
      required: true
      description: >-
        The unique identifier of the experience.
      schema:
        type: string
    scheduleIdParam:
      name: schedule_id
      in: path
      required: true
      description: >-
        The unique identifier of the schedule entry.
      schema:
        type: string
    bookingIdParam:
      name: booking_id
      in: path
      required: true
      description: >-
        The unique identifier of the booking.
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      description: >-
        The maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    offsetParam:
      name: offset
      in: query
      description: >-
        The number of results to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    Experience:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the experience.
        name:
          type: string
          description: >-
            The display name of the experience.
        description:
          type: string
          description: >-
            The full description of the experience and what guests will do.
        category:
          type: string
          description: >-
            The activity category of the experience.
          enum:
          - arts_and_culture
          - entertainment
          - food_and_drink
          - nature_and_outdoors
          - sports
          - tours
          - wellness
        status:
          type: string
          description: >-
            The current status of the experience on the platform.
          enum:
          - active
          - inactive
          - pending
          - suspended
        location:
          $ref: '#/components/schemas/ExperienceLocation'
        duration_minutes:
          type: integer
          description: >-
            The duration of the experience in minutes.
          minimum: 30
        max_guests:
          type: integer
          description: >-
            The maximum number of guests per session.
          minimum: 1
        pricing:
          $ref: '#/components/schemas/ExperiencePricing'
        languages:
          type: array
          description: >-
            The languages in which the experience is offered.
          items:
            type: string
        what_to_bring:
          type: array
          description: >-
            Items guests should bring to the experience.
          items:
            type: string
        accessibility:
          type: string
          description: >-
            Accessibility information for the experience.
        photos:
          type: array
          description: >-
            Photos showcasing the experience.
          items:
            $ref: '#/components/schemas/ExperiencePhoto'
        host:
          $ref: '#/components/schemas/ExperienceHost'
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the experience was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the experience was last updated.
    ExperienceCreate:
      type: object
      required:
      - name
      - description
      - category
      - location
      - duration_minutes
      - max_guests
      - pricing
      properties:
        name:
          type: string
          description: >-
            The display name of the experience.
          maxLength: 100
        description:
          type: string
          description: >-
            The full description of the experience and what guests will do.
          maxLength: 5000
        category:
          type: string
          description: >-
            The activity category of the experience.
          enum:
          - arts_and_culture
          - entertainment
          - food_and_drink
          - nature_and_outdoors
          - sports
          - tours
          - wellness
        location:
          $ref: '#/components/schemas/ExperienceLocation'
        duration_minutes:
          type: integer
          description: >-
            The duration of the experience in minutes.
          minimum: 30
        max_guests:
          type: integer
          description: >-
            The maximum number of guests per session.
          minimum: 1
        pricing:
          $ref: '#/components/schemas/ExperiencePricing'
        languages:
          type: array
          description: >-
            The languages in which the experience is offered.
          items:
            type: string
        what_to_bring:
          type: array
          description: >-
            Items guests should bring to the experience.
          items:
            type: string
        accessibility:
          type: string
          description: >-
            Accessibility information for the experience.
    ExperienceUpdate:
      type: object
      properties:
        name:
          type: string
          description: >-
            The display name of the experience.
          maxLength: 100
        description:
          type: string
          description: >-
            The full description of the experience and what guests will do.
          maxLength: 5000
        category:
          type: string
          description: >-
            The activity category of the experience.
          enum:
          - arts_and_culture
          - entertainment
          - food_and_drink
          - nature_and_outdoors
          - sports
          - tours
          - wellness
        location:
          $ref: '#/components/schemas/ExperienceLocation'
        duration_minutes:
          type: integer
          description: >-
            The duration of the experience in minutes.
          minimum: 30
        max_guests:
          type: integer
          description: >-
            The maximum number of guests per session.
          minimum: 1
        pricing:
          $ref: '#/components/schemas/ExperiencePricing'
        languages:
          type: array
          description: >-
            The languages in which the experience is offered.
          items:
            type: string
        what_to_bring:
          type: array
          description: >-
            Items guests should bring to the experience.
          items:
            type: string
        accessibility:
          type: string
          description: >-
            Accessibility information for the experience.
    ExperienceLocation:
      type: object
      required:
      - city
      - country
      properties:
        meeting_point:
          type: string
          description: >-
            Description of where guests should meet for the experience.
        city:
          type: string
          description: >-
            The city where the experience takes place.
        state:
          type: string
          description: >-
            The state or province where the experience takes place.
        country:
          type: string
          description: >-
            The ISO 3166-1 alpha-2 country code.
          pattern: '^[A-Z]{2}$'
        latitude:
          type: number
          format: double
          description: >-
            The latitude coordinate of the meeting point.
          minimum: -90
          maximum: 90
        longitude:
          type: number
          format: double
          description: >-
            The longitude coordinate of the meeting point.
          minimum: -180
          maximum: 180
    ExperiencePricing:
      type: object
      required:
      - price_per_person
      - currency
      properties:
        price_per_person:
          type: number
          format: double
          description: >-
            The price per guest in the specified currency.
          minimum: 0
        currency:
          type: string
          description: >-
            The ISO 4217 currency code for pricing.
          pattern: '^[A-Z]{3}$'
        group_discount:
          type: object
          description: >-
            Optional group discount configuration.
          properties:
            min_guests:
              type: integer
              description: >-
                Minimum number of guests to qualify for the group discount.
              minimum: 2
            discount_percent:
              type: number
              description: >-
                Percentage discount applied for group bookings.
              minimum: 0
              maximum: 100
    ExperiencePhoto:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the photo.
        url:
          type: string
          format: uri
          description: >-
            The URL where the photo is hosted.
        caption:
          type: string
          description: >-
            A caption describing the photo.
        sort_order:
          type: integer
          description: >-
            The display position of the photo.
    ExperienceHost:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the experience host.
        name:
          type: string
          description: >-
            The display name of the host.
        bio:
          type: string
          description: >-
            A short biography of the host.
        profile_picture_url:
          type: string
          format: uri
          description: >-
            The URL of the host profile picture.
        superhost:
          type: boolean
          description: >-
            Whether the host has Superhost status.
    Schedule:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the schedule entry.
        experience_id:
          type: string
          description: >-
            The identifier of the associated experience.
        date:
          type: string
          format: date
          description: >-
            The date of the scheduled session.
        start_time:
          type: string
          description: >-
            The start time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        end_time:
          type: string
          description: >-
            The end time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        max_guests:
          type: integer
          description: >-
            The maximum number of guests for this session.
          minimum: 1
        booked_guests:
          type: integer
          description: >-
            The current number of booked guests.
          minimum: 0
        available_spots:
          type: integer
          description: >-
            The number of remaining available spots.
          minimum: 0
        status:
          type: string
          description: >-
            The status of the schedule entry.
          enum:
          - open
          - full
          - cancelled
    ScheduleCreate:
      type: object
      required:
      - date
      - start_time
      properties:
        date:
          type: string
          format: date
          description: >-
            The date of the scheduled session.
        start_time:
          type: string
          description: >-
            The start time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        max_guests:
          type: integer
          description: >-
            Override the maximum number of guests for this specific session.
          minimum: 1
    ScheduleUpdate:
      type: object
      properties:
        start_time:
          type: string
          description: >-
            The updated start time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        max_guests:
          type: integer
          description: >-
            The updated maximum number of guests for this session.
          minimum: 1
        status:
          type: string
          description: >-
            The updated status of the schedule entry.
          enum:
          - open
          - cancelled
    Booking:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the booking.
        confirmation_code:
          type: string
          description: >-
            The human-readable confirmation code for the booking.
        status:
          type: string
          description: >-
            The current status of the booking.
          enum:
          - pending
          - confirmed
          - cancelled
          - completed
        experience_id:
          type: string
          description: >-
            The identifier of the booked experience.
        schedule_id:
          type: string
          description: >-
            The identifier of the booked schedule entry.
        guest:
          $ref: '#/components/schemas/BookingGuest'
        guests_count:
          type: integer
          description: >-
            The number of guests included in the booking.
          minimum: 1
        total_price:
          type: number
          format: double
          description: >-
            The total price of the booking.
        currency:
          type: string
          description: >-
            The ISO 4217 currency code for the booking pricing.
          pattern: '^[A-Z]{3}$'
        host_payout:
          type: number
          format: double
          description: >-
            The amount to be paid out to the host after fees.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the booking was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the booking was last updated.
    BookingGuest:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the guest.
        first_name:
          type: string
          description: >-
            The first name of the guest.
        last_name:
          type: string
          description: >-
            The last name of the guest.
        phone:
          type: string
          description: >-
            The phone number of the guest.
        verified:
          type: boolean
          description: >-
            Whether the guest has completed identity verification.
    ExperienceMessage:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the message.
        booking_id:
          type: string
          description: >-
            The identifier of the associated booking.
        sender_type:
          type: string
          description: >-
            Whether the message was sent by the host or guest.
          enum:
          - host
          - guest
        message:
          type: string
          description: >-
            The text content of the message.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the message was sent.
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: >-
            The total number of results available.
        limit:
          type: integer
          description: >-
            The number of results returned per page.
        offset:
          type: integer
          description: >-
            The current offset in the result set.
        has_more:
          type: boolean
          description: >-
            Whether more results are available beyond this page.