Introduction

The WineSitting API lets you connect your systems to your WineSitting account. Follow this guide to obtain an API key, validate your connection, and make your first request.

Before you start

You need:

• access to a WineSitting account;
• access to the target environment;
• a WineSitting API key.

caution

API keys grant access to your WineSitting data. Never commit them to source control or expose them in browser or mobile application code.

1. Choose an environment

WineSitting provides two environments:

Environment	Base URL	Purpose
Preproduction	https://preprod.winesitting.com/api/v2	Validate your integration with test data before going live.
Production	https://app.winesitting.com/api/v2	Work with your live WineSitting account and data.

Access is granted by WineSitting. Validate your integration in preproduction before sending production requests.

2. Generate an API key

Generate and manage your production API keys from the WineSitting dashboard. Contact WineSitting if you need access to preproduction or do not yet have an account.

Send the key with every request using the Bearer authentication scheme:

Authorization: Bearer YourBearerToken

3. Check the connection

Call the status endpoint to verify the environment URL and your API key:

curl --request GET \
  --url "https://app.winesitting.com/api/v2/status" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YourBearerToken"

A successful request returns:

[]

An HTTP 401 response means that the Bearer token is missing or invalid.

4. Make your first API request

Retrieve the account associated with the API key:

curl --request GET \
  --url "https://app.winesitting.com/api/v2/account" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YourBearerToken"

You can now use the API reference to explore the available resources, parameters, request bodies, and response examples.

Request conventions

Requests and responses use JSON unless an operation explicitly documents a file upload or download. Send Accept: application/json with JSON requests and add Content-Type: application/json when the request contains a JSON body.

WineSitting uses standard HTTP methods:

• GET retrieves a resource or collection;
• POST creates a resource or runs a calculation;
• PUT replaces an existing resource;
• DELETE removes a resource.

info

For PUT requests, send the complete resource representation, including unchanged values. Retrieve the current resource first, update the required fields, and then send the full payload.

Paths, parameters, and headers are case-sensitive. Always use the exact names shown in the reference.

Pagination

Paginated collection endpoints accept these optional query parameters:

Parameter	Default	Description
offset	0	Number of items to skip.
limit	30	Number of items to return, up to 500.
order	desc	Sort direction: asc or desc.

The X-Total-Count response header contains the total number of matching resources, independently of offset and limit.

curl --request GET \
  --url "https://app.winesitting.com/api/v2/orders?offset=20&limit=20&order=asc" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YourBearerToken"

The reference identifies which collection endpoints support pagination. For example, the consolidated Bottles endpoint returns the complete cellar and is not paginated.

Errors

WineSitting uses conventional HTTP response codes:

• 2xx means the request succeeded;
• 400 means the request or JSON payload is invalid;
• 401 means authentication failed;
• 403 means the account cannot perform the operation;
• 404 means the requested resource does not exist;
• 422 means validation failed;
• 5xx means an unexpected server error occurred.

Each operation documents its possible responses and their payloads. Do not rely only on the status text: inspect the returned JSON problem details when handling an error.

Data formats

• Dates and times use the Europe/Paris timezone unless an operation states otherwise.
• Country values use ISO 3166-1 alpha-2 codes, such as FR.
• Phone numbers use the E.164 format, such as +33612345678.
• JSON responses are encoded as UTF-8.

Next steps

• Retrieve and update the authenticated Account.
• Manage delivery Addresses.
• Retrieve the consolidated Cellar.
• Create and monitor Orders.
• Receive updates using Webhooks.