# Getting started

Welcome to the BookSpot OCTO API documentation. This API follows the [OCTO specification](https://docs.octo.travel/) for tours, activities, and attractions booking, with additional capabilities.

To learn more about how to set up your authentication token, please [read this help article](https://help.bookspot.io/en/articles/13002223-octo-integration).

## 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:

```http
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

```http
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

```http
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:

```json
{
  "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

{% stepper %}
{% step %}

### Get Products

List available products.
{% endstep %}

{% step %}

### Check Availability

Find available time slots.
{% endstep %}

{% step %}

### Create Reservation

Reserve a booking (expires if not confirmed).
{% endstep %}

{% step %}

### Confirm Booking

Finalize the booking.
{% endstep %}
{% endstepper %}

Products → Availability → Reserve → Confirm

## Next Steps

* [Supplier](https://docs.bookspot.io/octo-api-core/supplier) - Get supplier information
* [Products](https://docs.bookspot.io/octo-api-core/products) - List and retrieve products
* [Availability](https://docs.bookspot.io/octo-api-core/availability) - Check availability
* [Bookings](https://docs.bookspot.io/octo-api-core/bookings) - Manage bookings