# Posts

A 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](/docs/sources).

## Getting posts

```bash
# 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](/docs/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](/docs/people). |
| `data_points` | Extra facts about the post, mostly engagement. See [Data points](/docs/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](/docs/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](/docs/alerts).