Authentication
Vintrhall exposes a small read-only HTTP API for connecting external systems (order management, pricing tools, custom scripts) to your organization's data. All endpoints return JSON.
Getting an API key
Create a key in the app under Settings → API. The full key is shown once, right after creation. Vintrhall only stores a hash of it, so if you lose it there is no way to recover it: revoke it and create a new one instead.
A key looks like this:
vh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If a key leaks, revoke it from Settings → API immediately and create a new one. Revocation takes effect right away.
Making a request
Send the key in the Authorization header on every request:
Authorization: Bearer vh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Example with curl:
curl -H "Authorization: Bearer vh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
https://vintrhall.com/api/v1/products
Rate limits
Most endpoints share a limit of 60 requests per minute per organization. The stock export endpoint has its own separate limit of 30 requests per minute.
Errors
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "..." } | Invalid request, for example a bad limit or a malformed since timestamp. |
401 | { "error": "unauthorized" } | Missing, malformed, or revoked API key. |
429 | { "error": "..." } | Rate limit exceeded. The Retry-After header tells you how many seconds to wait before retrying. |
Pagination
List endpoints accept two query parameters:
| Parameter | Description |
|---|---|
cursor | Opaque token from a previous response. Omit it to get the first page. |
limit | Page size, default 100, maximum 200. |
Every list response has the same shape:
{
"items": [ ... ],
"nextCursor": "..."
}
Keep requesting the next page with nextCursor until it comes back as null, that means you have reached the end. Treat the cursor as an opaque string: do not try to parse or construct it yourself, it may change shape without notice.