The Airbnb Homes API provides partner developers with programmatic access to manage vacation rental listings on the Airbnb platform. It supports creating and updating property listings, managing descriptions, amenities, photos, pricing, and availability rules. The API also enables reservation management, calendar synchronization, guest messaging, and review handling.
openapi: 3.1.0
info:
title: Airbnb Homes API
description: >-
The Airbnb Homes API provides approved connectivity partners with
programmatic access to manage vacation rental listings on the Airbnb
platform. It supports creating and updating property listings, managing
descriptions, amenities, photos, pricing, and availability rules. The API
also enables reservation management, calendar synchronization, guest
messaging, and review handling. Access is restricted to approved
connectivity partners such as property management systems and channel
managers who integrate with Airbnb to help hosts manage their properties
at scale.
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: Calendar
description: >-
Operations for managing listing availability, pricing, and calendar
synchronization across platforms.
- name: Listings
description: >-
Operations for creating, reading, updating, and managing property
listings on Airbnb, including descriptions, amenities, and photos.
- name: Messages
description: >-
Operations for sending and retrieving guest and host messages within
reservation threads.
- name: Photos
description: >-
Operations for uploading, updating, and managing listing photos.
- name: Reservations
description: >-
Operations for managing reservations, including accepting, declining,
and retrieving booking details.
- name: Reviews
description: >-
Operations for retrieving and responding to guest and host reviews.
security:
- oauth2: []
paths:
/listings:
get:
operationId: listListings
summary: List All Listings
description: >-
Retrieves a paginated list of all property listings managed by the
authenticated partner. Supports filtering by status and other
listing attributes.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: status
in: query
description: >-
Filter listings by their current status on the platform.
schema:
type: string
enum:
- active
- inactive
- pending
- unlisted
responses:
'200':
description: A paginated list of listings.
content:
application/json:
schema:
type: object
properties:
listings:
type: array
items:
$ref: '#/components/schemas/Listing'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
description: Authentication credentials are missing or invalid.
'403':
description: The partner does not have permission to access listings.
post:
operationId: createListing
summary: Create a New Listing
description: >-
Creates a new property listing on Airbnb with the provided details
including property type, location, description, amenities, and
house rules. The listing will be in a pending state until all
required fields are completed and the listing is published.
tags:
- Listings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListingCreate'
responses:
'201':
description: The listing was successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
'400':
description: The request body contains invalid or missing fields.
'401':
description: Authentication credentials are missing or invalid.
/listings/{listing_id}:
get:
operationId: getListing
summary: Get a Listing
description: >-
Retrieves the full details of a specific property listing by its
unique identifier, including description, amenities, photos,
pricing, and availability configuration.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/listingIdParam'
responses:
'200':
description: The listing details.
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
put:
operationId: updateListing
summary: Update a Listing
description: >-
Updates an existing property listing with the provided fields.
Only the fields included in the request body will be modified.
This can be used to update descriptions, amenities, house rules,
and other listing attributes.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/listingIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListingUpdate'
responses:
'200':
description: The listing was successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
'400':
description: The request body contains invalid or missing fields.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
delete:
operationId: deleteListing
summary: Delete a Listing
description: >-
Removes a property listing from the Airbnb platform. This action
cannot be undone. Active reservations must be resolved before
a listing can be deleted.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/listingIdParam'
responses:
'204':
description: The listing was successfully deleted.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
'409':
description: The listing has active reservations and cannot be deleted.
/listings/{listing_id}/photos:
get:
operationId: listListingPhotos
summary: List Listing Photos
description: >-
Retrieves all photos associated with a specific listing, including
their captions, sort order, and dimensions.
tags:
- Photos
parameters:
- $ref: '#/components/parameters/listingIdParam'
responses:
'200':
description: A list of photos for the listing.
content:
application/json:
schema:
type: object
properties:
photos:
type: array
items:
$ref: '#/components/schemas/Photo'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
post:
operationId: uploadListingPhoto
summary: Upload a Listing Photo
description: >-
Uploads a new photo to a listing. Photos can include captions and
a sort order to control display position in the listing gallery.
tags:
- Photos
parameters:
- $ref: '#/components/parameters/listingIdParam'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- photo
properties:
photo:
type: string
format: binary
description: >-
The photo file to upload.
caption:
type: string
description: >-
An optional caption describing the photo.
sort_order:
type: integer
description: >-
The display position of the photo in the listing gallery.
responses:
'201':
description: The photo was successfully uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/Photo'
'400':
description: The uploaded file is invalid or exceeds size limits.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
/listings/{listing_id}/photos/{photo_id}:
delete:
operationId: deleteListingPhoto
summary: Delete a Listing Photo
description: >-
Removes a specific photo from a listing by its identifier.
tags:
- Photos
parameters:
- $ref: '#/components/parameters/listingIdParam'
- $ref: '#/components/parameters/photoIdParam'
responses:
'204':
description: The photo was successfully deleted.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing or photo was not found.
/listings/{listing_id}/calendar:
get:
operationId: getListingCalendar
summary: Get Listing Calendar
description: >-
Retrieves the availability calendar for a specific listing over a
date range. Returns day-by-day availability status, nightly pricing,
minimum stay requirements, and any blocked dates.
tags:
- Calendar
parameters:
- $ref: '#/components/parameters/listingIdParam'
- name: start_date
in: query
required: true
description: >-
The start date for the calendar range in ISO 8601 format.
schema:
type: string
format: date
- name: end_date
in: query
required: true
description: >-
The end date for the calendar range in ISO 8601 format.
schema:
type: string
format: date
responses:
'200':
description: The calendar data for the specified date range.
content:
application/json:
schema:
type: object
properties:
calendar_days:
type: array
items:
$ref: '#/components/schemas/CalendarDay'
'400':
description: The date range is invalid or missing.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
put:
operationId: updateListingCalendar
summary: Update Listing Calendar
description: >-
Updates the availability, pricing, and minimum stay settings for
specific dates on a listing calendar. Use this endpoint to block
or unblock dates, adjust nightly pricing, and set minimum stay
requirements.
tags:
- Calendar
parameters:
- $ref: '#/components/parameters/listingIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- calendar_operations
properties:
calendar_operations:
type: array
items:
$ref: '#/components/schemas/CalendarOperation'
responses:
'200':
description: The calendar was successfully updated.
'400':
description: The request body contains invalid operations.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing was not found.
/reservations:
get:
operationId: listReservations
summary: List Reservations
description: >-
Retrieves a paginated list of reservations for listings managed by
the authenticated partner. Supports filtering by status, listing,
and date range.
tags:
- Reservations
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: status
in: query
description: >-
Filter reservations by their current status.
schema:
type: string
enum:
- pending
- accepted
- denied
- cancelled
- checked_in
- checked_out
- name: listing_id
in: query
description: >-
Filter reservations by listing identifier.
schema:
type: string
- name: start_date
in: query
description: >-
Filter reservations with check-in dates on or after this date.
schema:
type: string
format: date
- name: end_date
in: query
description: >-
Filter reservations with check-in dates on or before this date.
schema:
type: string
format: date
responses:
'200':
description: A paginated list of reservations.
content:
application/json:
schema:
type: object
properties:
reservations:
type: array
items:
$ref: '#/components/schemas/Reservation'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
description: Authentication credentials are missing or invalid.
/reservations/{reservation_id}:
get:
operationId: getReservation
summary: Get a Reservation
description: >-
Retrieves the full details of a specific reservation including
guest information, dates, pricing breakdown, and current status.
tags:
- Reservations
parameters:
- $ref: '#/components/parameters/reservationIdParam'
responses:
'200':
description: The reservation details.
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
/reservations/{reservation_id}/accept:
post:
operationId: acceptReservation
summary: Accept a Reservation
description: >-
Accepts a pending reservation request. Once accepted, the
reservation is confirmed and the calendar dates are blocked.
tags:
- Reservations
parameters:
- $ref: '#/components/parameters/reservationIdParam'
responses:
'200':
description: The reservation was successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
'409':
description: The reservation is not in a pending state.
/reservations/{reservation_id}/deny:
post:
operationId: denyReservation
summary: Deny a Reservation
description: >-
Denies a pending reservation request. A reason for denial may
be provided to inform the guest.
tags:
- Reservations
parameters:
- $ref: '#/components/parameters/reservationIdParam'
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: >-
The reason for denying the reservation request.
responses:
'200':
description: The reservation was successfully denied.
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
'409':
description: The reservation is not in a pending state.
/reservations/{reservation_id}/cancel:
post:
operationId: cancelReservation
summary: Cancel a Reservation
description: >-
Cancels an accepted reservation. Cancellation policies and fees
may apply depending on the listing configuration and timing.
tags:
- Reservations
parameters:
- $ref: '#/components/parameters/reservationIdParam'
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: >-
The reason for cancelling the reservation.
responses:
'200':
description: The reservation was successfully cancelled.
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
'409':
description: The reservation cannot be cancelled in its current state.
/reservations/{reservation_id}/messages:
get:
operationId: listReservationMessages
summary: List Reservation Messages
description: >-
Retrieves the message thread for a specific reservation, including
all messages exchanged between the host and guest.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/reservationIdParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
responses:
'200':
description: A paginated list of messages in the reservation thread.
content:
application/json:
schema:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
post:
operationId: sendReservationMessage
summary: Send a Reservation Message
description: >-
Sends a new message in the reservation thread from the host to
the guest. Messages are delivered through the Airbnb messaging
system.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/reservationIdParam'
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/Message'
'400':
description: The message content is invalid or exceeds length limits.
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
/reservations/{reservation_id}/reviews:
get:
operationId: listReservationReviews
summary: List Reservation Reviews
description: >-
Retrieves the reviews associated with a specific reservation,
including both the guest review and host response if available.
tags:
- Reviews
parameters:
- $ref: '#/components/parameters/reservationIdParam'
responses:
'200':
description: The reviews for the reservation.
content:
application/json:
schema:
type: object
properties:
reviews:
type: array
items:
$ref: '#/components/schemas/Review'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The reservation was not found.
/listings/{listing_id}/reviews:
get:
operationId: listListingReviews
summary: List Listing Reviews
description: >-
Retrieves a paginated list of all reviews for a specific listing,
including guest ratings and comments.
tags:
- Reviews
parameters:
- $ref: '#/components/parameters/listingIdParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
responses:
'200':
description: A paginated list of reviews for the listing.
content:
application/json:
schema:
type: object
properties:
reviews:
type: array
items:
$ref: '#/components/schemas/Review'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The listing 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. Access tokens
expire after 24 hours and must be refreshed.
flows:
authorizationCode:
authorizationUrl: https://www.airbnb.com/oauth2/auth
tokenUrl: https://api.airbnb.com/v2/oauth2/authorizations
scopes:
listings:read: Read listing information
listings:write: Create and update listings
reservations:read: Read reservation information
reservations:write: Accept, deny, and cancel reservations
messages:read: Read reservation messages
messages:write: Send messages to guests
reviews:read: Read reviews
calendar:read: Read calendar availability
calendar:write: Update calendar availability and pricing
parameters:
listingIdParam:
name: listing_id
in: path
required: true
description: >-
The unique identifier of the listing.
schema:
type: string
reservationIdParam:
name: reservation_id
in: path
required: true
description: >-
The unique identifier of the reservation.
schema:
type: string
photoIdParam:
name: photo_id
in: path
required: true
description: >-
The unique identifier of the photo.
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:
Listing:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the listing.
name:
type: string
description: >-
The display name of the listing.
description:
type: string
description: >-
The full description of the property.
property_type:
type: string
description: >-
The type of property being listed.
enum:
- apartment
- house
- secondary_unit
- unique_space
- bed_and_breakfast
- boutique_hotel
room_type:
type: string
description: >-
The type of room or space being offered.
enum:
- entire_home
- private_room
- shared_room
status:
type: string
description: >-
The current status of the listing on the platform.
enum:
- active
- inactive
- pending
- unlisted
address:
$ref: '#/components/schemas/Address'
bedrooms:
type: integer
description: >-
The number of bedrooms in the property.
minimum: 0
bathrooms:
type: number
description: >-
The number of bathrooms in the property.
minimum: 0
beds:
type: integer
description: >-
The total number of beds in the property.
minimum: 0
max_guests:
type: integer
description: >-
The maximum number of guests allowed.
minimum: 1
amenities:
type: array
description: >-
The list of amenity identifiers available at the property.
items:
type: string
house_rules:
type: string
description: >-
The house rules and guidelines for guests.
check_in_time:
type: string
description: >-
The earliest check-in time in HH:MM format.
pattern: '^[0-2][0-9]:[0-5][0-9]$'
check_out_time:
type: string
description: >-
The latest check-out time in HH:MM format.
pattern: '^[0-2][0-9]:[0-5][0-9]$'
pricing:
$ref: '#/components/schemas/Pricing'
photos:
type: array
description: >-
The photos associated with the listing.
items:
$ref: '#/components/schemas/Photo'
cancellation_policy:
type: string
description: >-
The cancellation policy applied to the listing.
enum:
- flexible
- moderate
- strict
- strict_14_with_grace_period
- super_strict_30
- super_strict_60
created_at:
type: string
format: date-time
description: >-
The timestamp when the listing was created.
updated_at:
type: string
format: date-time
description: >-
The timestamp when the listing was last updated.
ListingCreate:
type: object
required:
- name
- property_type
- room_type
- address
- max_guests
properties:
name:
type: string
description: >-
The display name of the listing.
maxLength: 50
description:
type: string
description: >-
The full description of the property.
maxLength: 5000
property_type:
type: string
description: >-
The type of property being listed.
enum:
- apartment
- house
- secondary_unit
- unique_space
- bed_and_breakfast
- boutique_hotel
room_type:
type: string
description: >-
The type of room or space being offered.
enum:
- entire_home
- private_room
- shared_room
address:
$ref: '#/components/schemas/Address'
bedrooms:
type: integer
description: >-
The number of bedrooms in the property.
minimum: 0
bathrooms:
type: number
description: >-
The number of bathrooms in the property.
minimum: 0
beds:
type: integer
description: >-
The total number of beds in the property.
minimum: 0
max_guests:
type: integer
description: >-
The maximum number of guests allowed.
minimum: 1
amenities:
type: array
description: >-
The list of amenity identifiers available at the property.
items:
type: string
house_rules:
type: string
description: >-
The house rules and guidelines for guests.
check_in_time:
type: string
description: >-
The earliest check-in time in HH:MM format.
pattern: '^[0-2][0-9]:[0-5][0-9]$'
check_out_time:
type: string
description: >-
The latest check-out time in HH:MM format.
pattern: '^[0-2][0-9]:[0-5][0-9]$'
cancellation_policy:
type: string
description: >-
The cancellation policy applied to the listing.
enum:
- flexible
- moderate
- strict
- strict_14_with_grace_period
- super_strict_30
- super_strict_60
ListingUpdate:
type: object
properties:
name:
type: string
description: >-
The display name of the listing.
maxLength: 50
description:
type: string
description: >-
The full description of the property.
maxLength: 5000
property_type:
type: string
description: >-
The type of property being listed.
enum:
- apartment
- house
- secondary_unit
- unique_space
- bed_and_breakfast
- boutique_hotel
room_type:
type: string
description: >-
The type of room or space being offered.
enum:
- entire_home
- private_room
- shared_room
bedrooms:
type: integer
description: >-
The number of bedrooms in the property.
minimum: 0
bathrooms:
type: number
description: >-
The number of bathrooms in the property.
minimum: 0
beds:
type: integer
description: >-
The total number of beds in the property.
minimum: 0
max_guests:
type: integer
description: >-
The maximum number of guests allowed.
minimum: 1
amenities:
type: array
description: >-
The list of amenity identifiers available at the property.
items:
type: string
house_rules:
type: string
description: >-
The house rules and guidelines for guests.
check_in_time:
type: string
description: >-
The earliest check-in time in HH:MM format.
pattern: '^[0-2][0-9]:[0-5][0-9]$'
check_out_time:
type: string
description: >-
The latest check-out time in HH:MM format.
pattern: '^[0-2][0-9]:[0-5][0-9]$'
cancellation_policy:
type: string
description: >-
The cancellation policy applied to the listing.
enum:
- flexible
- moderate
- strict
- strict_14_with_grace_period
- super_strict_30
- super_strict_60
Address:
type: object
required:
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/airbnb/refs/heads/main/openapi/airbnb-homes-api-openapi.yml