Posts
MarkdownA post is one item from a publication. One newsletter issue, one podcast episode, one blog post. Posts are what you search, and what an alert matches against.
Every post belongs to one source.
Getting posts
# Search across everything
/api/v1/posts/search?q=%22Acme%22&window=month
# Newest first, for one publication
/api/v1/posts?source=<slug>
# One post in full
/api/v1/posts/<slug>
Search ranks by relevance and adds a snippet showing the match. Browse gives you a chronological feed. See Search.
Fields on every post
| Field | What it holds |
|---|---|
slug |
The key. Pass this back, not the title. |
sputnik_url |
The post's page on Sputnik. Link to this. |
title |
The post title. |
link |
The publisher's own URL. Different from sputnik_url. |
author |
As the publication declared it, unparsed. For people we identified, use people. |
published_at |
When the publisher dated it. Null when the feed carries no date. |
source |
The publication it came from: slug and name. |
excerpt |
A short summary, where the feed gives one. |
snippet |
Search results only. The matched text, with <b> around the hit. |
categories |
The publication's own tags. Sparse and unnormalised. |
transcript_status |
Podcast episodes. Whether a transcript exists yet. |
Fields you only get on one post
These are too big or too expensive to put on every row of a list.
| Field | What it holds |
|---|---|
text_content |
The body of a newsletter or blog post. |
enclosure_url |
The audio file, for a podcast episode. |
people |
Who we credited on it, each with their role. See People. |
data_points |
Extra facts about the post, mostly engagement. See Data points. |
original_metadata |
Extra values from the feed, such as duration_seconds. |
Reading the content
Newsletters and blog posts have their words in text_content, which comes back when you ask for one post.
Podcast episodes do not. Their words are in the transcript, which is a separate request because an episode runs to hundreds of kilobytes. See Transcripts.
/api/v1/posts/<slug>/transcript
Two posts that look the same
A publication sometimes ships the same piece more than once, for example a corrected version, or the same episode on two feeds. We group those and return one post. The one you get is the version we consider canonical.
Dates
published_at is when the publisher says it went out. It is not when we found it. Some feeds carry no date at all, and those posts have published_at: null.
Alert hits carry their own created_at, which is when we found the match. See Alerts.