AI agents
The issue format
What an issue looks like when your agent fetches it as markdown.
When an agent calls get_issue, it gets one issue as markdown: YAML frontmatter, then the body of the issue, then a ## Transcript section when the issue is also a podcast episode.
Frontmatter
---
slug: "an-example-issue"
title: "An example issue"
newsletter: "Example Weekly"
newsletter_slug: "example-weekly"
author: "Jane Doe"
published_at: "2026-10-27T08:00:00+00:00"
permalink_url: "https://example.com/p/an-example-issue"
newsletter_homepage_url: "https://example.com"
feed_url: "https://example.com/feed"
platform: "substack"
language: "en"
body_word_count: 1840
---
Fields with no value are left out. The fields are:
| Field | What it holds |
|---|---|
slug |
The issue slug, to use with get_issue |
title |
The title of the issue |
newsletter, newsletter_slug |
The name and slug of the newsletter |
author |
The author, when we know it |
published_at |
The publication time (ISO 8601) |
permalink_url |
The link to the original issue |
newsletter_homepage_url, feed_url |
The newsletter's homepage and feed |
platform, language |
The platform it is published on, and its language |
body_word_count |
How long the issue is, so an agent can decide whether to read it in full |
audio_url, audio_duration_seconds, transcript_word_count |
Only when the issue is also a podcast episode |
New fields can be added over time, so read them by name.
Body
The body is the issue as markdown: headings, links, lists and quotes are kept, and layout markup is dropped.
Check the length first
Some issues are long. list_issues returns word counts without the text, so an agent can pick which issues to fetch in full.