# Introduction

This section provides practical use cases demonstrating the main API endpoints.

## Authenticate

Visit the [dedicated documentation page](/authentication/oidc) to learn how to authenticate with the Korus Ticket API

## Http Requests

In the following sections every curl command is executed with the following headers :

- `Authorization` header containing the JWT token issued by the authentication endpoint
- `Accept-Language` header that controls the language of all translated fields (names, descriptions, error messages)
returned in HTTP responses. Pass a valid [BCP 47](https://tools.ietf.org/html/bcp47) language tag such as `fr`,
`en`, or `es`. If the requested language is not supported by the catalog, the catalog's default language is used
instead. When downloading order documents, this header also selects the language of the generated PDF if available.


Also, to simplify the examples curl `GET` commands returning a list of elements will use the `page` and `itemsPerPage`
pagination parameters to get a short and lisible response.

## Catalog access

For the following sections your organization needs to have access to a catalog. To list catalogs accessible to your
organization, you can use the [GET /v1/ticketing/catalogs](/openapi/ticketingcatalog/api_v1ticketingcatalogs_get_collection) endpoint.

### Request

```bash
curl --request GET \
  --url https://api.korusticket.com/v1/ticketing/catalogs \
  --header 'accept: application/ld+json' \
  --header 'Authorization: Bearer {{YOUR_JWT_TOKEN}}' \
  --header 'Accept-Language: fr'
```

### Response

```json
{
  "@context": "/contexts/TicketingCatalog",
  "@id": "/v1/ticketing/catalogs",
  "@type": "Collection",
  "totalItems": 1,
  "member": [
    {
      "@id": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e",
      "@type": "TicketingCatalog",
      "id": "0194abdc-3a71-72b0-a9b9-89d4be0cd73e",
      "createdAt": "2025-01-28T07:42:04+00:00",
      "name": "Catalogue Puy du Fou - CSE"
    }
  ],
  "view": {
    "@id": "/v1/ticketing/catalogs?catalog=0193afd5-2ae2-78a9-866a-e4592fe5eba",
    "@type": "PartialCollectionView"
  },
  "search": {
    "@type": "IriTemplate",
    "template": "/v1/ticketing/catalogs{?}",
    "variableRepresentation": "BasicRepresentation",
    "mapping": []
  }
}
```

The response shows that you have access to the "Catalogue Puy du Fou - CSE" catalog
️

Important
If no catalogs appear in the HTTP response, please contact [Korusticket Support](mailto:contact@korusticket.com).

To learn how to search for products inside a catalog, please refer to this [page](/how-to/browse-a-catalog)

## Caching Strategy and API Usage

To ensure optimal performance for both your application and the Korus API, we strongly recommend implementing an appropriate caching strategy based on data type:

#### Data to cache (24h recommended):

- Product catalog: Product base, product, product options, offers, tickets and sessions. Since this data is relatively stable, avoid querying the API on every display. Cache the catalog and refresh it once daily.


#### Real-time data (1 min cache recommended):

- Availability: Due to high volatility, query the API in real-time.
- Pricing: Less volatile than availability, but rates can fluctuate several times per day, make calls when needed.


Important: Do not use the Korus API as your primary backend by making systematic calls on every user interaction. This approach would degrade performance and could result in rate limiting.