Quickstart
Authenticate
| Base URL | |
|---|---|
| Sandbox | https://api.dev.currentsplatform.com |
| Production | https://api.currentsplatform.com |
Set the base URL and your key once; every example below is relative to them.
Code
Every request carries the key as a bearer token:
Code
A request without a valid key is refused. Keys are issued per environment, so a key that works against the sandbox will not work against production.
Categories that are ready now
Two categories are prepared ahead of time and return a full edition the moment you register them, so you can read the shape of a real response without waiting out the warming window:
pet carefitness clothing
Either comes back ready rather than warming, with the same fields in the
same shape as a category we start watching for you. Send a brief with one and
its topics are narrowed and reordered against it, exactly as they would be for
a category of your own.
Register a category
A category is a plain phrase — what you would call the shelf your products sit on.
Code
Code
The optional brief describes what you sell. When you send one, the topics you get back are narrowed and ordered by how close they sit to it, so a cat-food advertiser and a dog-crate advertiser watching the same category see different topics first.
Wait for it to warm
status is warming until we have watched the category long enough to say
something worth bidding on, which takes about a day. ready_at tells you the
moment — there is no value in polling before it.
See what you hold
Code
Code
Newest first. ready_at appears only while a category is warming, and an archived
category carries the reason it was archived. next_update_at is when each
category's next edition lands, so you can schedule a single pass instead of
polling each one in turn; an archived category has no next edition, so the field
is absent.
Read its topics
Code
Code
Topics come ordered by attention_index, so the one holding the most attention
leads whichever way it is moving — read momentum_index and trajectory for that.
Here the biggest topic is the one to exit and the second is the one to buy. Two topics
shown here; a reading returns up to ten. Every field is in the
API reference.
Fetch once per day. next_update_at is when the next edition lands; between
editions the response does not change.
Rate limits
Per account:
| Limit | |
|---|---|
| Reading a category | 60 per minute |
| Registering or archiving a category | 10 per hour |
Limits are per account, not per key — every key you hold draws on the same budget, so adding a key does not add headroom.
A topic set is rebuilt once every 24 hours, so reading more often than that
returns the same edition. next_update_at tells you when the next one lands;
polling before then spends your budget for nothing.
Over the limit you get 429, with headers saying when the window resets.
Sandbox limits
Two limits hold in the sandbox on top of the rate limits above.
| Limit | |
|---|---|
| Active categories | 3 at a time |
| Tracking, per category you register | 3 days from registration |
Registering a fourth category is refused until you archive one of the three. The prepared categories count towards the three like any other.
Categories subscribed in sandbox are auto archived after 3 days.
When a category's three days are up we archive it for you. It reads exactly as an
archive of your own does: status is archived, and archive_reason says why.
pet care and fitness clothing are served from prepared editions rather than
tracked, so they are never archived this way and stay readable for as long as you
hold them.
Stop tracking
Code
A reason is required.
Reading the category afterwards tells you it is archived and why, and nothing else:
Code
No topics come back. The editions built before you archived it describe a moment that has passed, and nothing is built for the category after it. Subscribe to it again to resume tracking and receive topics.