Developers · Client API v1
Sync your catalog. Pull your learning analytics.
The ToldUntold Client API is a server-to-server REST API for your PIM, ERP, OMS, BI warehouse or HRIS. Scoped keys, flat JSON errors, predictable pagination, idempotent writes. You won't need an OAuth flow or an SDK.
Request
curl -s https://api.staging.tolduntold.com/v1/client/catalog/status \
-H "Authorization: Bearer tuk_9f2c1a4b6d8e0f2a4c6e8b0d.$SECRET"Response · 200 OK
{
"brand_id": 8347,
"key_id": "tuk_9f2c1a4b6d8e0f2a4c6e8b0d",
"name": "ERP production",
"scopes": ["catalog.products:read", "catalog.stock:write"],
"expires_at": null
}Two domains, one key
A single tuk_ key can carry scopes on both domains. The brand and permissions come from the key itself; you never send them in the request.
Products · Variants · Stock
Catalog
Keep your ToldUntold catalog in sync from your PIM, ERP or OMS: create and update products, generate variants in bulk, push stock snapshot feeds, adjust stock with optimistic locking.
27 endpoints · read & write
Read the guide Metrics · Users · Read-only
Analytics
Pull learning analytics into your BI warehouse or HRIS: daily brand aggregates, per-content metrics and pseudonymised per-user rows, complete up to the previous day every morning.
5 endpoints · read-only
Read the guide Time to first call
Three steps to a 200
01
Request access
Tell us what you're connecting and to which environment. A human reviews every request and answers within two business days.
02
Store your key
You receive a tuk_ key scoped to your brand. The secret is shown once, so put it in your secret manager before you close the tab.
03
Make the first call
Call the status endpoint. It needs a valid key but no scope, and echoes your brand, key name and granted scopes. You're live.
First call
curl https://api.staging.tolduntold.com/v1/client/catalog/status \
-H "Authorization: Bearer $TUK_KEY"Auth at a glance
Key anatomy
tuk_9f2c1a4b6d8e0f2a4c6e8b0d.<secret>tuk_<key_id>: the public key id, safe to log.
<secret>: shown once at creation, stored only as a SHA-256 hash. Lost it? Rotate the key.
Authorization header
Authorization: Bearer tuk_<key_id>.<secret>- One brand per key. The brand comes from the key itself; no path contains a brand id.
- Scopes gate every endpoint. Cross-brand or unknown resources return a flat 404, never a 403.
- Errors are flat JSON (code, message, and an optional errors map) with stable machine-readable codes.
- Writes are idempotent: send an Idempotency-Key header; replays return the original response.
- Rate limits apply per key and per brand, with X-RateLimit-* headers and Retry-After on 429.
ToldUntold issues the keys; there is no self-service in v1. Rotation mints a successor key and revokes the old one atomically.
Download the contracts
Each domain ships an OpenAPI 3.1 contract, the authoritative source for exact shapes. Import it to generate clients, mocks and tests, or start from the Postman collection.
Get started
Ready to integrate?
Tell us what you're connecting. A person reads every request and answers within two business days.
Just exploring? The guides and contracts are public; you don't need an account.
Training. Intelligence. Content Production. Visual Merchandising. AI. One platform built for retail performance.