> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Voyant REST API

## Base URL

All API requests should be made to:

```
https://api.voyantcloud.com
```

<Info>
  The API is delivered via a global edge network for low-latency access worldwide.
</Info>

## API version

The current API version is **v1**. All endpoints are prefixed with `/v1`:

```
https://api.voyantcloud.com/v1/products
```

## Request format

### Headers

Include these headers in every request:

| Header          | Required       | Description                  |
| --------------- | -------------- | ---------------------------- |
| `Authorization` | Yes            | `Bearer YOUR_API_KEY`        |
| `Content-Type`  | For POST/PATCH | `application/json`           |
| `Accept`        | Optional       | `application/json` (default) |

<Info>
  Workspace context is automatically determined from your API key. You don't need to pass a workspace ID.
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.voyantcloud.com/v1/products \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.voyantcloud.com/v1/products", {
    headers: {
      Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
    },
  })
  ```
</CodeGroup>

### Request body

For `POST` and `PATCH` requests, send data as JSON:

```javascript theme={null}
{
  "productId": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
  "departureId": "dept_01h9xm2n3p4q5r6s7t8v9w0x1y",
  "pax": {
    "adults": 2,
    "children": 1
  }
}
```

## Resource identifiers

All resources use prefixed IDs that indicate the entity type:

```
prod_01h8z3y4x2w1v0u9t8s7r6q5p4
└──┘
prefix (prod = product)
```

Common prefixes: `prod` (product), `dept` (departure), `book` (booking), `ppl` (person), `inv` (invoice).

The API validates that IDs have the correct prefix for each field. See [Identifiers](/concepts/identifiers) for the full list.

## Response format

### Success responses

Successful requests return JSON with appropriate HTTP status codes:

* `200 OK` - Request succeeded
* `201 Created` - Resource created successfully
* `204 No Content` - Request succeeded with no response body

```json theme={null}
{
  "id": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
  "title": "Paris City Tour",
  "status": "active"
}
```

### Response headers

Every response includes helpful headers:

| Header                  | Description                             |
| ----------------------- | --------------------------------------- |
| `X-Request-ID`          | Unique request identifier for debugging |
| `X-RateLimit-Limit`     | Maximum requests per minute             |
| `X-RateLimit-Remaining` | Remaining requests in current window    |
| `X-RateLimit-Reset`     | Unix timestamp when limit resets        |
| `Content-Type`          | Always `application/json`               |

Example response headers:

```
X-Request-ID: req_abc123def456
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2988
X-RateLimit-Reset: 1704067200
Content-Type: application/json
```

## Error responses

Errors return standard HTTP status codes with JSON error objects:

```json theme={null}
{
  "error": "Error message description"
}
```

See [Error handling](/api-reference/errors) for complete error reference.

## Pagination

List endpoints support pagination using query parameters:

| Parameter | Type    | Default | Description              |
| --------- | ------- | ------- | ------------------------ |
| `limit`   | integer | 50      | Items per page (max 100) |
| `offset`  | integer | 0       | Number of items to skip  |

<RequestExample>
  ```bash theme={null}
  curl "https://api.voyantcloud.com/v1/products?limit=20&offset=40" \
    -H "Authorization: Bearer $VOYANT_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [...],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 40,
      "has_more": true
    }
  }
  ```
</ResponseExample>

<Tip>Use `has_more` to determine if more pages are available without calculating page numbers.</Tip>

## Filtering

Many list endpoints support filtering via query parameters:

```bash theme={null}
# Filter products by status
/v1/products?status=active

# Filter by type
/v1/products?type=tour

# Multiple filters
/v1/products?status=active&type=tour
```

<Note>
  Available filters vary by endpoint. Check individual endpoint documentation for supported filters.
</Note>

## Sorting

List endpoints support sorting with the `sort` parameter:

```bash theme={null}
# Sort by creation date (descending)
/v1/products?sort=-created_at

# Sort by title (ascending)
/v1/products?sort=title
```

Prefix with `-` for descending order, omit for ascending.

## Idempotency

`POST` requests support idempotency using the `Idempotency-Key` header:

```bash theme={null}
curl -X POST https://api.voyantcloud.com/v1/bookings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"productId": "prod_123"}'
```

<Tip>
  Use UUIDs or unique request identifiers as idempotency keys to safely retry requests without
  duplicates.
</Tip>

## Rate limiting

API requests are rate-limited per workspace:

**Live workspaces:**

* 3,000 requests per minute
* 30 requests per second burst

**Sandbox workspaces:**

* 100 requests per minute
* 5 requests per second burst

Pricing is usage-based—no plan tiers or upgrades required.

Rate limit information is included in response headers:

```
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2988
X-RateLimit-Reset: 1704067200
```

When you exceed rate limits, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "retry_after": 30
}
```

<Warning>
  Implement exponential backoff when receiving 429 responses. Excessive rate limit violations may
  result in temporary API access suspension.
</Warning>

## API endpoints

### Products

Manage your travel product catalog:

<CardGroup cols={2}>
  <Card title="List products" icon="list" href="/api-reference/products/list-products">
    `GET /v1/products`
  </Card>

  <Card title="Get product" icon="box" href="/api-reference/products/get-product">
    `GET /v1/products/:id`
  </Card>

  <Card title="Pricing options" icon="tag" href="/api-reference/products/pricing-options">
    `GET /v1/products/:id/pricing/options`
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/api-reference/products/extensions">
    `GET /v1/products/:id/extensions`
  </Card>
</CardGroup>

### Bookings

Create and manage travel bookings:

<CardGroup cols={2}>
  <Card title="Create booking" icon="calendar-plus" href="/api-reference/bookings/create">
    `POST /v1/bookings`
  </Card>

  <Card title="Get booking" icon="calendar" href="/api-reference/bookings/get">
    `GET /v1/bookings/:id`
  </Card>

  <Card title="Wizard session" icon="wand-magic-sparkles" href="/api-reference/bookings/wizard-session">
    `POST /v1/bookings/wizard/session`
  </Card>
</CardGroup>

### Departures

Manage departure dates and pricing:

<CardGroup cols={2}>
  <Card title="Get departure" icon="plane-departure" href="/api-reference/departures/get">
    `GET /v1/departures/:id`
  </Card>

  <Card title="Calculate price" icon="calculator" href="/api-reference/departures/price">
    `POST /v1/departures/:id/price`
  </Card>
</CardGroup>

## Webhooks

Receive real-time notifications for events in your workspace:

* Booking created, updated, cancelled
* Payment succeeded, failed, refunded
* Product created, updated, published
* Customer created, updated

See the [Webhooks guide](/concepts/webhooks) for event types, signature verification, and setup instructions.

## Support

Need help with the API?

<CardGroup cols={2}>
  <Card title="Email support" icon="envelope">
    [help@voyantcloud.com](mailto:help@voyantcloud.com)
  </Card>

  <Card title="Documentation" icon="book">
    You're reading it!
  </Card>
</CardGroup>

## Next steps

<Steps>
  <Step title="Authentication">
    Learn how to [authenticate your requests](/authentication) with API keys
  </Step>

  <Step title="Quickstart">
    Follow the [quickstart guide](/quickstart) to make your first request
  </Step>

  <Step title="Explore endpoints">
    Browse endpoint documentation starting with [Products](/api-reference/products/list-products)
  </Step>
</Steps>