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

# Quickstart

> Get started with the Voyant API in under 5 minutes

## Prerequisites

Before you begin, make sure you have:

* A Voyant account with workspace access
* Your API key (generate from workspace settings)
* Basic understanding of REST APIs
* A tool to make HTTP requests (cURL, Postman, or code)

<Warning>
  Never expose your API key in client-side code or public repositories. Always keep it secure on
  your server.
</Warning>

## Get your API key

<Steps>
  <Step title="Log in to your dashboard">
    Navigate to [https://dash.voyantcloud.com](https://dash.voyantcloud.com) and sign in to your workspace.
  </Step>

  <Step title="Open settings">Click on your workspace settings icon in the sidebar navigation.</Step>

  <Step title="Generate API key">
    Under the **API Keys** section, click **Generate New Key**. Copy the key immediately as it will only be shown once.

    <Check>
      Store your API key securely in environment variables or a secrets manager.
    </Check>
  </Step>
</Steps>

## Make your first request

Let's fetch your product catalog to verify authentication works.

<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}`,
    },
  })

  const products = await response.json()
  console.log(products)
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
    'https://api.voyantcloud.com/v1/products',
    headers={'Authorization': f"Bearer {os.environ['VOYANT_API_KEY']}"}
  )

  products = response.json()
  print(products)
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = getenv('VOYANT_API_KEY');

  $ch = curl_init('https://api.voyantcloud.com/v1/products');
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $apiKey"]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $products = json_decode(curl_exec($ch), true);
  curl_close($ch);

  print_r($products);
  ?>
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 Success theme={null}
  [
    {
      "id": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
      "title": "Paris City Tour",
      "status": "active",
      "type": "tour",
      "currency": "EUR",
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "prod_01h8z4y5x3w2v1u0t9s8r7q6p5",
      "title": "Rome Food Experience",
      "status": "active",
      "type": "experience",
      "currency": "EUR",
      "created_at": "2024-01-20T14:30:00Z"
    }
  ]
  ```
</ResponseExample>

<Check>If you see a list of products, your API key is working correctly! 🎉</Check>

## Get product details

Now let's fetch detailed information about a specific product:

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

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

  const product = await response.json()
  console.log(product)
  ```

  ```python Python theme={null}
  import requests
  import os

  product_id = "prod_01h8z3y4x2w1v0u9t8s7r6q5p4"
  response = requests.get(
    f'https://api.voyantcloud.com/v1/products/{product_id}',
    headers={'Authorization': f"Bearer {os.environ['VOYANT_API_KEY']}"}
  )

  product = response.json()
  print(product)
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "id": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
    "title": "Paris City Tour",
    "description": "Discover the magic of Paris with our comprehensive city tour...",
    "status": "active",
    "type": "tour",
    "duration_days": 1,
    "currency": "EUR",
    "location": {
      "city": "Paris",
      "country": "FR"
    },
    "media": [
      {
        "url": "https://cdn.voyantcloud.com/products/paris-tour-1.jpg",
        "type": "image",
        "sort": 0
      }
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
  ```
</ResponseExample>

## Calculate a price

Use the pricing endpoint to get real-time price calculations with taxes and rules applied:

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voyantcloud.com/v1/departures/dept_01h9xm2n3p4q5r6s7t8v9w0x1y/price \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "productId": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
      "pax": {
        "adults": 2,
        "children": 1,
        "infants": 0
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "breakdown": {
      "base": {
        "label": "Base",
        "amount": 150.00
      },
      "lines": [
        {
          "label": "Per person",
          "qty": 3,
          "unitAmount": 50.00,
          "amount": 150.00
        }
      ],
      "taxes": [
        {
          "rate": 19,
          "amount": 28.50,
          "jurisdiction": null
        }
      ]
    },
    "net": 150.00,
    "tax": 28.50,
    "gross": 178.50,
    "total": 178.50,
    "taxesIncluded": false
  }
  ```
</ResponseExample>

## Error handling

The API uses standard HTTP status codes and returns detailed error messages:

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Not found"
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>

<Tip>
  Always check the HTTP status code first, then parse the error message from the response body.
</Tip>

## Response headers

Every API response includes helpful headers:

```
X-Request-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2988
X-RateLimit-Reset: 1704067200
Content-Type: application/json
```

* **X-Request-ID**: Unique identifier for the request (include when reporting issues)
* **X-RateLimit-\***: Rate limiting information
* **Content-Type**: Always `application/json`

## Next steps

Now that you've made your first requests, explore more advanced features:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API key management and security best practices
  </Card>

  <Card title="Products API" icon="box" href="/api-reference/products/list-products">
    Explore the complete product catalog endpoints
  </Card>

  <Card title="Bookings API" icon="calendar-check" href="/api-reference/bookings/create">
    Create and manage travel bookings programmatically
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/api-reference/errors">
    Handle errors gracefully in your integration
  </Card>
</CardGroup>

## Common patterns

### Environment variables

Store your API key in environment variables:

<Tabs>
  <Tab title=".env file">
    ```bash theme={null}
    VOYANT_API_KEY=your_api_key_here
    VOYANT_API_URL=https://api.voyantcloud.com
    ```
  </Tab>

  <Tab title="Shell export">
    ```bash theme={null}
    export VOYANT_API_KEY="your_api_key_here"
    export VOYANT_API_URL="https://api.voyantcloud.com"
    ```
  </Tab>
</Tabs>

### Base request function

Create a reusable function for API requests:

<CodeGroup>
  ```javascript Node.js theme={null}
  async function voyantRequest(endpoint, options = {}) {
    const response = await fetch(
      `${process.env.VOYANT_API_URL}${endpoint}`,
      {
        ...options,
        headers: {
          Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      }
    );

  if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error || 'API request failed');
  }

  return response.json();
  }

  // Usage
  const products = await voyantRequest('/v1/products');

  ```

  ```python Python theme={null}
  import requests
  import os

  def voyant_request(endpoint, method='GET', data=None):
      url = f"{os.environ['VOYANT_API_URL']}{endpoint}"
      headers = {
          'Authorization': f"Bearer {os.environ['VOYANT_API_KEY']}",
          'Content-Type': 'application/json'
      }

      response = requests.request(
          method, url, headers=headers, json=data
      )
      response.raise_for_status()
      return response.json()

  # Usage
  products = voyant_request('/v1/products')
  ```
</CodeGroup>

<Check>You're now ready to build your travel booking integration with Voyant! 🚀</Check>