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

# API overview

> Prerequisites and best practices for integrating with the Voyado Elevate API

The Voyado Elevate API enables server- and client-side integrations through HTTP requests that return raw JSON data, enabling unlimited flexibility and customization. The API handles communication with the Voyado Elevate cluster and includes both automatic load balancing and failover.

The API has three main integration areas: imports to bring products and content into Elevate, queries to retrieve results, and notifications to share visitor behavior with Elevate for reporting and behavior analysis.

A [JavaScript library](/elevate/docs/api/javascript-library), including TypeScript models, is available to facilitate client-side integrations to Voyado Elevate using the HTTP API.

## Prerequisites

To get started with the Voyado Elevate API integration, a few prerequisites must be met.

* [Origin host and cross-origin resource sharing](#origin-host-and-cross-origin-resource-sharing) available
* [Cluster credentials](/elevate/docs/home/getting-started#credentials) received
* [Connection requirements](#connection-requirements) met

Once these have been met, read through [Tips and best practices](#tips-and-best-practices) and continue with integrating queries and notifications using the [Storefront API](/elevate/docs/api/storefront/overview). Meanwhile, products and content are imported using the [Admin API](/elevate/docs/api/admin/overview).

### Origin host and cross-origin resource sharing

Cross-origin resource sharing (CORS) is a mechanism for controlling what domain Ajax requests to the cluster are allowed to originate from. Voyado can help with the origin host configuration as part of the customer onboarding process, if you provide the necessary information.

Default configuration allows Ajax requests originating from all origins, but restricting access to the API is recommended. The following information is needed from the customer to configure the origin host correctly:

* Protocols (HTTP/HTTPS)
* Domains (subdomains)
* Ports (80, 443)

### Connection requirements

* [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) <Icon icon="external-link" size={12} /> version 1.3 is recommended. Version 1.2 is supported.
* [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) <Icon icon="external-link" size={12} /> enabled.
* A CA certificate store that trusts Amazon root certificates. For more information, see the [Amazon Trust Services Repository](https://www.amazontrust.com/repository/) <Icon icon="external-link" size={12} />.
* [HTTP](https://en.wikipedia.org/wiki/HTTP) <Icon icon="external-link" size={12} /> version 2 is recommended. Version 1.1 is also supported.
* **Deprecated:** a CA certificate store that trusts Let’s Encrypt root certificates. For more information, see [Let’s Encrypt Certificate Compatibility](https://letsencrypt.org/docs/certificate-compatibility/) <Icon icon="external-link" size={12} />.

## Tips and best practices

### Caching

A general rule of thumb is to never cache Elevate-generated responses. Caching prevents personalization and can cause notifications to be erroneous due to cached tickets. This does not include static data and resources such as images, which can be cached.

### Bots and crawlers

To keep your Elevate usage and analytics accurate, ensure you allow well-known crawlers (for example, Googlebot) but block or throttle unwanted bots. Detect bots early and avoid calling Elevate APIs for them. Learn more in [Handling bots and crawlers](/elevate/docs/guides/operations/bots-and-crawlers).

### Request parameters

Query parameters are case-sensitive.

### Request headers

The APIs support various request headers.

| Name              | Values                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Accept-Encoding` | `gzip`                                                                  | Enables compressed [gzip](https://en.wikipedia.org/wiki/Gzip) <Icon icon="external-link" size={12} /> responses. For optimal performance, it is advised to consistently use compressed responses.                                                                                                                                                                                                                            |
| `Accept`          | `application/json;charset=utf-8`, `application/jsonlines;charset=utf-8` | Format that the client can process in the request.                                                                                                                                                                                                                                                                                                                                                                           |
| `Content-Type`    | `application/json;charset=utf-8`, `text/plain; charset=utf-8`           | Format of the data being sent, JSON is recommended. To support large requests with unique page configurations, queries can be performed through HTTP `POST`. Queries return JSON objects as responses, but requests in browsers with `application/json` as `Content-Type` automatically trigger a preflight request. To avoid this, `text/plain` is supported as `Content-Type` and can be used in client-side integrations. |
| `User-Agent`      | `PostmanRuntime/1.2.3`                                                  | For internal tracking and troubleshooting, as well as to support potential future features, it is recommended to include a `User-Agent` header in HTTP API requests.                                                                                                                                                                                                                                                         |

## Utility resources

### OpenAPI specifications

Each version of each API contains a downloadable OpenAPI specification that can be used with tools such as [Swagger UI](https://swagger.io/tools/swagger-ui/) <Icon icon="external-link" size={12} />. The OpenAPI specifications are found under [Specifications](/elevate/docs/api/specifications) for the corresponding API version.

### Postman collections

Each version of each API contains a downloadable Postman collection that can be tested using the tool [Postman](https://www.postman.com/) <Icon icon="external-link" size={12} />. The collections are found under [Postman collections](/elevate/docs/api/postman).

#### Setting environment variables

Note that the file uses environment variables, located under the **Variables** tab in the Postman interface. To run the requests, the `cluster-id` variable must first be changed. The `cluster-id` will automatically be applied to the `baseUrl` parameter.