Getting started

Welcome to the BookSpot OCTO API documentation. This API follows the OCTO specification for tours, activities, and attractions booking, with additional capabilities.

Base URL

All API requests should be made to:

https://api.bookspot.io/octo/v1

Authentication

All API requests require Bearer token authentication.

Getting Your API Token

1. Log in to your BookSpot account

2. Navigate to Settings → Integrations → OCTO API

3. Click Create Token

4. Copy your token and store it securely

Using Your Token

Include the token in the Authorization header:

Authorization: Bearer your-api-token-here

Required Headers

Every request must include the following headers:

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Octo-Capabilities	Yes	Comma-separated list of enabled capabilities
Accept-Language	No	Preferred language (ISO 639-1 code, e.g., sv, en)

Example Request

GET /octo/v1/products HTTP/1.1
Host: your-domain.com
Authorization: Bearer your-api-token-here
Octo-Capabilities: pricing,content,extras
Accept-Language: sv

Capabilities

Capabilities are optional features that extend the API response. Enable them by including them in the Octo-Capabilities header.

Capability	Description
pricing	Include pricing information (in minor currency units)
content	Include localized content (titles, descriptions)
extras	Include addon products (extras) for units

Example

To enable pricing and content:

Octo-Capabilities: pricing,content

To enable all capabilities:

Octo-Capabilities: pricing,content,extras

Content Localization

When the content capability is enabled, you can request content in a specific language using the Accept-Language header.

Request

Accept-Language: sv

Response Headers

Header	Description
Content-Language	The language used in the response
Octo-Available-Languages	Comma-separated list of available languages

Error Handling

The API returns errors in the following format:

{
  "error": "ERROR_CODE",
  "errorMessage": "Human-readable description of the error"
}

Common Error Codes

Code	HTTP Status	Description
INVALID_PRODUCT_ID	400	The product ID was invalid or not found
INVALID_BOOKING_UUID	400	The booking UUID was invalid or not found
UNPROCESSABLE_ENTITY	400	Request is valid but cannot be processed
Unauthorized	401	Invalid or missing authentication token

API Flow

1

Get Products

List available products.

2

Check Availability

Find available time slots.

3

Create Reservation

Reserve a booking (expires if not confirmed).

4

Confirm Booking

Finalize the booking.

Products → Availability → Reserve → Confirm

Next Steps

• Supplier - Get supplier information

• Products - List and retrieve products

• Availability - Check availability

• Bookings - Manage bookings