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.
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.
f
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/airbnb/refs/heads/main/openapi/airbnb-activities-api-openapi.yml