---
title: "Suggest sources for a show."
method: GET
path: "/show-source-suggestions"
tags: ["Shows"]
---

# Suggest sources for a show.

`GET /show-source-suggestions`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/show-source-suggestions`
- Auth: HTTP bearer

A short list of interesting sources to suggest when the writer has no feed in mind: NASA, arXiv, Wikipedia's daily features, the Library of Congress, public-domain archives, the Federal Register, USGS, and a topic searched in the news. Each comes ready to save as one of `setup.sources`, with the schedule it suits and what one episode covers, how much text its items carry (a headlines feed makes a thin episode, so it suits a weekly roundup), and a note on who owns the material. Free. Save a suggestion's `source` as one of `setup.sources` (PATCH /publishing-series/{seriesId}/show), changing what its `customize` note says, then read it with POST /publishing-series/{seriesId}/show/check-sources.

## Query parameters

- `topic` string

## Response `200`

The suggestions.

- ShowSourceSuggestions: A short list of interesting sources to suggest when the writer has no feed in mind: NASA, arXiv, Wikipedia's daily features, the Library of Congress, public-domain archives, the Federal Register, USGS, and a topic searched in the news. Each comes ready to save as one of `setup.sources`, with the schedule it suits and what one episode covers, how much text its items carry (a headlines feed makes a thin episode, so it suits a weekly roundup), and a note on who owns the material. Free.
  - `suggestions` object[], required
    - `id` string, required
    - `title` string, required
    - `pitch` string, required
    - `source` union, required: Ready to save as one of `setup.sources`.
      - object: An RSS or Atom feed: a blog, a newsletter (Substack: https://<name>.substack.com/feed), an arXiv listing (https://rss.arxiv.org/rss/cs.RO), Product Hunt. Each feed entry is one item.
        - `adapter` 'rss', required
        - `params` object, required
          - `feedUrl` string, uri, required: The feed URL (http or https).
          - `maxItems` integer: The most entries read per run. Default 12.
          - `lookbackDays` integer: How many days back to read. Defaults to the schedule: 1 for a daily one, 7 for a weekly one, 31 for a monthly one.
          - `readArticles` boolean: true reads each entry's linked page whole (the same reader a Hacker News thread's article goes through); an entry whose page is paywalled or unreadable is passed over. Off (the default), an entry is the feed's own text, shortened past 8,000 characters.
          - `order` string: "newest" (the default) reads what the feed published in the window. "oldest" works through the feed's archive instead: the oldest entries no episode has covered yet, whatever their date, so a feed that carries its whole history (a newsletter, a podcast, a blog) becomes a backlog the show reads in order.
        - `label` string
      - object: A topic searched on the web at each run: the newest articles about it, each one item, never one an earlier episode covered. Searches run on Sleeper's own search service (no key needed), up to 40 a day per account.
        - `adapter` 'web-search', required
        - `params` object, required
          - `query` string, required: What to search for, as you would type it ("solid-state battery breakthroughs", "Mars sample return").
          - `topic` string: "news" (the default) searches news coverage; "general" searches the whole web.
          - `site` string: Only results from this site, as a host name ("nasa.gov").
          - `maxItems` integer: The most articles taken per run. Default 5.
          - `lookbackDays` integer: How many days back to read. Defaults to the schedule: 1 for a daily one, 7 for a weekly one, 31 for a monthly one.
        - `label` string
      - object: Hacker News front-page discussions, from the top 100: each story with enough comments is one item, carrying its whole comment thread (every comment, with who replied to whom) and its linked article read whole.
        - `adapter` 'hackernews', required
        - `params` object
          - `count` integer: The most stories taken per run. Default 5.
          - `minComments` integer: A story needs at least this many comments, by Hacker News' own count. Default 10.
          - `itemId` string: One specific story id instead of the front page.
          - `skipObituaries` boolean: true passes over a thread about a real person's death (from its title, the post and the article's opening); the next thread takes its place. Off by default.
        - `label` string
      - object: A public GitHub repository: its releases, merged pull requests and commit flow over the window, as one item.
        - `adapter` 'github', required
        - `params` object, required
          - `repo` string, required: The repository as owner/name.
          - `lookbackDays` integer: How many days back to read. Defaults to the schedule: 1 for a daily one, 7 for a weekly one, 31 for a monthly one.
        - `label` string
      - object: One web page, read whole at each run (a changelog, a status page, a running list).
        - `adapter` 'url-watch', required
        - `params` object, required
          - `url` string, uri, required: The page URL (http or https).
          - `label` string: What to call the page in the episode material.
        - `label` string
      - object: Text the writer supplies once (notes, an archive excerpt). The same text every run, so pair it with another source.
        - `adapter` 'upload', required
        - `params` object, required
          - `text` string, required: The text itself, up to 12,000 characters.
          - `label` string: What to call the text in the episode material.
        - `label` string
    - `customize` string
    - `suggested` object, required
      - `every` 'day' | 'week' | 'month', required
      - `covers` 'item' | 'roundup', required
    - `richness` 'articles' | 'summaries' | 'headlines', required
    - `rights` string, required
    - `topics` string[], required
  - `note` string

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)