yDrink Data API

Your yDrink data in your own systems, whenever you want it: the same datasets as our data feeds, with what changed and when.

Getting started

1. Your yDrink contact sends a one-time link to your key. Open it, press Show my key, and keep the key somewhere safe, like a secrets manager. It's shown once.

2. Send it on every request:

curl -H "Authorization: Bearer ydk_live_..." https://api.ydr.ink/v1/status

3. /v1/status lists the datasets you get, the periods each holds and your current version. Pull each dataset once, keep the version, and from then on pull only what changed (Staying in sync).

Keys and IP limits

Keys belong to your company, and you can have several (say one for production, one for testing). A key can be limited to your servers' IPs or ranges; ask your yDrink contact to set them. To replace a key, we send a new link, and the old key keeps working for a week after you open it, so you can switch without downtime. If a key gets out, tell us and we'll turn it off at once.

Staying in sync

Every response carries version (and the header X-Data-Version). The version goes up when your data is rebuilt and something in it changed.

GET /v1/changes?since=1041
{"version": 1077, "since": 1041, "full_refresh": false, "datasets": {
  "brand_monthly": {"full_refresh": false, "periods": ["2025-10-31", "...", "2026-09-30"], "from": "2025-10", "to": "2026-09"},
  "brand_weekly": {"full_refresh": false, "periods": ["202639", "202640", "202641", "202642"], "from": "202639", "to": "202642"},
  "accounts": {"full_refresh": false, "changed": true, "pull": "/v1/accounts?changed_since=1041"}}}

For each dataset, delete the listed periods on your side and pull them again with from and to. For accounts and merges, pull the rows changed since your version. Then keep the new version. When a dataset says full_refresh: true, pull all of that dataset again: it's new to you (say, a dataset just added to your service), its history was corrected, or since is 0. The top-level full_refresh is true when any dataset is. Usually the newest month plus the 11 before it, and the newest weeks, change with each update.

Apply merges too: /v1/accounts/merges lists accounts found to be the same place. Move your history from merged_id to surviving_id.

Dates and periods

Monthly rows carry sales_date, the last day of the month: 2026-09-30. Weekly rows carry yearweek, like 202642; weeks start on Sunday. In from and to, give months as 2026-09 and weeks as 202642.

Paging and CSV

Each response is one page of up to about 10000 rows. When there's more, next_cursor (and the header X-Next-Cursor) holds a cursor: send it back as ?cursor= with the same other parameters for the next page, until it's null. For CSV, add ?format=csv or send Accept: text/csv; the cursor is then only in X-Next-Cursor.

Limits and headers

• Requests a minute, per key (usually 60).
• Rows a day for your company, reset at midnight Central. It's generous: about 100 times all your data.
• Requests at once for your company (usually 2).

Every answered response has X-RateLimit-Limit and X-RateLimit-Remaining (rows today) and X-RateLimit-Reset. Past 80% of the day's rows, pages are half size and responses carry a Warning header. A refused request gets 429 and Retry-After. Every response has X-Request-Id: quote it to support. /v1/usage shows your last 30 days.

Errors

Errors are JSON: {"error": {"code": "quota", "message": "...", "request_id": "..."}}. Match on code.

Endpoints

Field names follow the yDrink Data Integrations dictionary. Questions: your yDrink contact, or howdy@ydrink.net. Access is permitted under license. © yDrink. All rights reserved.