Endpoint reference

A chronological feed. Give at most one scope — collection, source, person, topic or sponsor — to narrow it; they are alternative ways of cutting the same list, not filters that compose, so passing two is a 422 with code: scope_conflict.

For relevance-ranked search, use GET /api/v1/posts/search.

Ranked by relevance by default, or by recency for a chronological stream of mentions.

Bare space-separated terms are ANDed, and may match anywhere in a document — on a two-hour transcript, comfort food matches an episode saying "comfort" in the intro and "food" an hour later. Quote a phrase you mean as a phrase. Quoted phrases match an exact word sequence; uppercase AND/OR/NOT combine terms; field:value scopes to title, body, transcript or author. Malformed syntax is repaired rather than rejected.

There is deliberately **no person filter** here. We credit a person on far too few posts for it to be a filter worth trusting, and a keyword search for the name finds more. Chronological browse still takes person, because that reads the credits directly rather than the index.

The full record, including body text where we hold it.

Paged speaker turns, with real names substituted for "Speaker 1" wherever we could identify them. This is the only way to read a transcript — the words are never inlined on the post itself.

transcript_status rides alongside the envelope so a caller that gets zero turns can tell "not transcribed yet" from "transcribed, but empty".

Adds what they have been talking about lately and where they appear. topics is empty for anyone whose posts predate topic extraction.

With no q, the browsable list of everything we index.

Adds what it has been covering lately and which brands have advertised on it.

With q, all-time matches for that name; without it, the most-covered topics of the last 90 days.

**This index is capped, not paged.** It returns at most 100 rows, next_cursor is always null, and total goes null when the cap was hit. Passing cursor is a 422 — narrow with q instead. Past the first hundred, a ranked list of a million topics is not something anyone reads, and the query stops being cheap.

Adds the publications covering it most and the people credited on its posts. For the posts themselves, use GET /api/v1/posts?topic=<slug>.

With q, all-time matches for that brand name, matched case-insensitively; without it, the most-heard sponsors of the last 90 days.

Capped rather than paged, exactly like topics.

**Read these as ads that ran, not deals a show signed.** Programmatic insertion puts spots into feeds the publisher never sold — a physics channel's transcript reads out ads a streaming platform placed, not sponsors it found.

Adds the shows the brand has been heard on, most appearances first.

Both the collections your team owns and the global ones Sputnik curates. is_global tells them apart; global ones are readable by everyone and editable by no one.

Created empty. Add publications with POST /collections/{collection}/sources.

Only the given fields change. Which publications are in it is a separate thing.

Removes the set, not the publications in it.

Adding one already in it is a no-op, so this is safe to retry.

A project is usually one of your own customers. Archived ones are hidden unless you ask for them.

Setting is_active to false archives it and switches off every alert in it. Setting it back to true restores the project but leaves those alerts off — turning monitoring back on should be a decision, not a side effect.

Takes its alerts and their hits with it. Archive instead if you want the history.

An alert belongs to a project and holds up to ten saved searches; a post hits the alert if any of them matches.

search is a convenience that creates the alert's first saved search in the same call, so "watch for this" is one request. It is nested because an alert and its search both have a name — search.q and search.name are exactly what the searches endpoint takes.

A new alert delivers nowhere until you give it a destination. That state is legal, and the app flags it.

With its searches, its destinations and its hit count. The hits themselves come from GET /alert-hits.

Changes only what is true of the notification — its name, its project, whether it is on. What it looks for lives on its searches; where it delivers on its destinations.

Takes its hits with it. Set is_active to false instead to stop it matching while keeping the history.

Takes q and the same filter names GET /posts/search takes, so a search that worked lifts straight into an alert without renaming anything.

A search added today starts finding hits on the next run, which looks back a day. It does not reach further back: an alert reports new things, and the history of a query belongs in search.

An alert holds ten searches; the eleventh is a 422.

Applies from the next run onwards. It does not re-run the new definition over the past — that would report old posts as news.

Deactivates rather than deletes: hits exist because this search found them, and removing it outright orphans that explanation. PATCH is_active back to true to restore it.

Give exactly one of email or webhook. The channel comes from the webhook rather than being passed in — the two must agree, and this is the only way to guarantee it.

Adding a destination does not replay history: hits already delivered stay delivered, so connecting a webhook in week three does not fire hundreds of events about things you have already seen.

A resumable stream, not an ordinary page. next_cursor is a resume token: store it, pass it back as cursor, and you get only what has arrived since. It keeps coming back non-null even when there is nothing new, so poll it rather than waiting for null.

Each hit carries the post, the alert, and which of its searches matched.

Registered once for the team and reusable by any of its alerts, in any project. The signing secret comes back on every read.

Registering one delivers nothing on its own — point an alert at it with POST /alerts/{alert}/destinations.

Switching one back on also clears its failure streak, so an endpoint you have just fixed gets a fresh run of attempts rather than deactivating itself on its very next failure.

Blocked with a 422 while any alert still delivers here: cascading would silently mute those alerts, and you would find out by not being told about something. PATCH is_active to false instead.