Currents
Getting started

Quickstart

Authenticate

Base URL
Sandboxhttps://api.dev.currentsplatform.com
Productionhttps://api.currentsplatform.com

Set the base URL and your key once; every example below is relative to them.

TerminalCode
export CURRENTS_API=https://api.dev.currentsplatform.com export CURRENTS_API_KEY=your_key_here

Every request carries the key as a bearer token:

TerminalCode
curl "$CURRENTS_API/v1/categories/pet%20care" \ -H "Authorization: Bearer $CURRENTS_API_KEY"

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 care
  • fitness 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.

TerminalCode
curl -X POST "$CURRENTS_API/v1/categories" \ -H "Authorization: Bearer $CURRENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"category": "home fitness", "brief": "adjustable dumbbells"}'
JSONCode
{ "category": "home fitness", "status": "warming", "ready_at": "2026-09-22T09:14:33Z" }

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

TerminalCode
curl "$CURRENTS_API/v1/categories" \ -H "Authorization: Bearer $CURRENTS_API_KEY"
JSONCode
[ { "category": "pet care", "status": "ready", "next_update_at": "2026-09-22T06:00:00Z", "subscribed_at": "2026-09-21T09:12:04Z" }, { "category": "home fitness", "status": "warming", "ready_at": "2026-09-22T09:14:33Z", "next_update_at": "2026-09-22T07:14:33Z", "subscribed_at": "2026-09-21T09:14:33Z" } ]

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

TerminalCode
curl "$CURRENTS_API/v1/categories/pet%20care" \ -H "Authorization: Bearer $CURRENTS_API_KEY"
JSONCode
{ "category": "pet care", "status": "ready", "prepared_at": "2026-09-22T06:00:00Z", "next_update_at": "2026-09-23T06:00:00Z", "taxonomy": { "name": "iab-content-3.1", "cattax": 9 }, "highlights": { "big": ["cat-grooming", "rescue-and-adoption"], "fast_moving": ["aquarium-keeping", "rescue-and-adoption", "dog-training-and-behaviour"], "uncontested": ["pet-bird-care"] }, "topics": [ { "topic": "cat-grooming", "iab": { "ids": ["424"], "path": "Pets > Cats" }, "terms": ["cat grooming", "sphynx cat", "feline acne", "grooming gloves"], "attention_index": 96, "momentum_index": 50, "trajectory": "softening", "why_now": "Deshedding and nail-trim shorts that carried this topic through August are being published less often, and newer uploads are under-performing their age peers.", "scale": "broad", "brand_presence": "saturated", "creator_spread": "moderate", "brands_present": ["heiniger", "catit", "wahl"], "intent_mix": { "entertainment": 0.43, "research_a_purchase": 0.2, "routine_care": 0.2, "solve_a_problem": 0.1, "other": 0.07 }, "audience_mood": { "tone": "inquisitive", "positive_share": 0.35, "commercial_signal": "high", "top_questions": ["What brush is that?", "How often should I do this?"] }, "suitability": { "risk": "low", "categories": [], "risk_mix": { "low": 0.94, "medium": 0.06 } }, "evidence": [ "https://youtu.be/TbFVCaKxbds", "https://youtu.be/ME3IymLeShI", "https://youtu.be/a4IFcW8BINA" ] }, { "topic": "aquarium-keeping", "iab": { "ids": ["426"], "path": "Pets > Fish and Aquariums" }, "terms": ["aquarium", "betta", "aquascaping", "planted tank"], "attention_index": 82, "momentum_index": 88, "trajectory": "surging", "why_now": "Planted-tank and betta setup uploads are arriving from more channels than last month and out-pacing their age peers.", "scale": "niche", "brand_presence": "active", "creator_spread": "diverse", "brands_present": ["fluval", "tropica", "green aqua"], "intent_mix": { "entertainment": 0.57, "routine_care": 0.2, "research_a_purchase": 0.13, "solve_a_problem": 0.1 }, "audience_mood": { "tone": "inquisitive", "positive_share": 0.52, "commercial_signal": "high", "top_questions": ["What substrate is that?", "How often do you change the water?"] }, "suitability": { "risk": "low", "categories": [], "risk_mix": { "low": 0.97, "medium": 0.03 } }, "evidence": [ "https://youtu.be/v0GsGAcVE0k", "https://youtu.be/OT3ZJHnf51o", "https://youtu.be/9s6eZ_bQ8SQ" ] } ] }

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 category60 per minute
Registering or archiving a category10 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 categories3 at a time
Tracking, per category you register3 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

TerminalCode
curl -X DELETE "$CURRENTS_API/v1/categories/pet%20care?reason=campaign+ended" \ -H "Authorization: Bearer $CURRENTS_API_KEY"

A reason is required.

Reading the category afterwards tells you it is archived and why, and nothing else:

JSONCode
{ "status": "archived", "archive_reason": "campaign ended" }

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.

Last modified on