# 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.

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

Every request carries the key as a bearer token:

```bash
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.

```bash
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"}'
```

```json
{ "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

```bash
curl "$CURRENTS_API/v1/categories" \
  -H "Authorization: Bearer $CURRENTS_API_KEY"
```

```json
[
  { "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

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

```json
{
  "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](/docs/api).

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.

:::info{title="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

```bash
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:

```json
{ "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.
