Docs/Publishing

Publishing

Host podcasts on Fountain: manage feeds and items. A feed/item is the internal representation of a public show/episode.

List Feeds

GEThttps://api.fountain.fm/v1/feeds

List every feed you can access.

Responses

200Your feeds.

feedsFeed[]required

The feeds you host.

Example request

curl -X GET "https://api.fountain.fm/v1/feeds" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "feeds": [
    {
      "id": "a1b2c3d4",
      "fountain_id": "show:id:def456",
      "title": "Citadel Dispatch",
      "author": "ODELL",
      "description": "Freedom tech and Bitcoin, live and unedited.",
      "categories": [
        "Technology",
        "News"
      ],
      "explicit": false,
      "display_email": false,
      "links": [
        "https://citadeldispatch.com"
      ],
      "image": "https://media.fountain.fm/shows/a1b2c3d4/cover.jpg",
      "vocabulary": [
        "Nostr",
        "sats"
      ],
      "rss_url": "https://feeds.fountain.fm/a1b2c3d4",
      "updated": "2026-02-18T22:03:53.467Z"
    }
  ]
}

Load Feed

GEThttps://api.fountain.fm/v1/feeds/{feed_id}

Load a single feed by ID.

Path parameters

feed_idstringrequired

The feed to read.

Responses

200The feed.

feedFeedrequired

The feed.

Example request

curl -X GET "https://api.fountain.fm/v1/feeds/{feed_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "feed": {
    "id": "a1b2c3d4",
    "fountain_id": "show:id:def456",
    "title": "Citadel Dispatch",
    "author": "ODELL",
    "description": "Freedom tech and Bitcoin, live and unedited.",
    "categories": [
      "Technology",
      "News"
    ],
    "explicit": false,
    "display_email": false,
    "links": [
      "https://citadeldispatch.com"
    ],
    "image": "https://media.fountain.fm/shows/a1b2c3d4/cover.jpg",
    "vocabulary": [
      "Nostr",
      "sats"
    ],
    "rss_url": "https://feeds.fountain.fm/a1b2c3d4",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Update Feed

PATCHhttps://api.fountain.fm/v1/feeds/{feed_id}

Edit a feed. The body is the patch: a value sets the field, null clears it, an absent key leaves it unchanged. image_id is a READY FEED_IMAGE upload (see Start Upload). On a published feed, a required field (title, author, description, image_id, categories) can't be cleared.

Path parameters

feed_idstringrequired

The feed to edit.

Request body

Omitted fields stay unchanged. null clears a nullable field.

titlestring | nulloptional

Feed title.

authorstring | nulloptional

Feed author.

descriptionstring | nulloptional

Feed description in Markdown. Max 4000 characters when converted to HTML.

categoriesPodcastCategory[] | nulloptional

Apple Podcasts categories. Max 3.

explicitboolean | nulloptional

Mark the feed as explicit.

display_emailboolean | nulloptional

Show the owner email in the feed.

linksstring[] | nulloptional

Associated URLs. Max 3.

vocabularystring[] | nulloptional

Terms that help the AI transcriber. Max 224 tokens.

image_idstring | nulloptional

ID of a READY FEED_IMAGE upload.

Responses

200The updated feed.

feedFeedrequired

The updated feed.

Example request

curl -X PATCH "https://api.fountain.fm/v1/feeds/{feed_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Citadel Dispatch","categories":["Technology","News"],"explicit":false}'

Request body

{
  "title": "Citadel Dispatch",
  "categories": [
    "Technology",
    "News"
  ],
  "explicit": false
}

Response · 200

{
  "ok": true,
  "feed": {
    "id": "a1b2c3d4",
    "fountain_id": "show:id:def456",
    "title": "Citadel Dispatch",
    "author": "ODELL",
    "description": "Freedom tech and Bitcoin, live and unedited.",
    "categories": [
      "Technology",
      "News"
    ],
    "explicit": false,
    "display_email": false,
    "links": [
      "https://citadeldispatch.com"
    ],
    "image": "https://media.fountain.fm/shows/a1b2c3d4/cover.jpg",
    "vocabulary": [
      "Nostr",
      "sats"
    ],
    "rss_url": "https://feeds.fountain.fm/a1b2c3d4",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Feed Stats

GEThttps://api.fountain.fm/v1/feeds/{feed_id}/stats

Read the download stats of a podcast, artist or album feed, plus payment stats once it is published. An artist’s downloads come from its albums. Unpublished feeds report downloads only. group_by dimensions differ in coverage: CONTENT and APP cover both downloads and payments, COUNTRY/KIND/PLATFORM are downloads-only (revenue and supporters 0), and ACTION/SUPPORTER are payments-only (downloads 0). Under CONTENT each group.content is a hosting item id, or an album feed id for an artist. Rows from deleted items and livestreams are omitted from the breakdown but still counted in the feed totals.

Path parameters

feed_idstringrequired

The feed to read stats for.

Query parameters

startstringoptional

ISO-8601 inclusive range start; also enables the previous comparison window.

endstringoptional

ISO-8601 inclusive range end.

bucketstringoptional

Bucket size for the buckets time series: DAY, WEEK or MONTH. Omit for totals only.

group_bystringoptional

Comma-separated breakdown dimensions: CONTENT, COUNTRY, KIND, PLATFORM, APP, ACTION, SUPPORTER.

Responses

200The feed stats.

statsStatsrequired

The feed stats.

Example request

curl -X GET "https://api.fountain.fm/v1/feeds/{feed_id}/stats" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "stats": {
    "rows": [
      {
        "group": {},
        "total": {
          "downloads": 1240,
          "revenue_usd": 32.5,
          "revenue_satoshis": 48210,
          "supporters": 18
        },
        "previous": {
          "downloads": 980,
          "revenue_usd": 24,
          "revenue_satoshis": 35600,
          "supporters": 14
        }
      }
    ],
    "meta": {}
  }
}

List Items

GEThttps://api.fountain.fm/v1/feeds/{feed_id}/items

List a feed's items, newest first, up to 100 per page. Pass the returned next_cursor back as ?cursor= for the next page; when it is absent, you have reached the last page.

Path parameters

feed_idstringrequired

The feed whose items to list.

Query parameters

cursorstringoptional

A next_cursor from a previous page. Omit for the first page.

Responses

200A page of items.

itemsItem[]required

The items.

next_cursorstringoptional

Pass back as ?cursor= for the next page. Absent on the last page.

Example request

curl -X GET "https://api.fountain.fm/v1/feeds/{feed_id}/items" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "items": [
    {
      "id": "e5f6g7h8",
      "fountain_id": "episode:id:abc123",
      "title": "The Genesis Block",
      "description": "We dig into the **first block** ever mined.",
      "season_number": 2,
      "item_number": 14,
      "links": [
        "https://citadeldispatch.com/cd141"
      ],
      "explicit": false,
      "status": "PUBLISHED",
      "image": "https://media.fountain.fm/episodes/e5f6g7h8/cover.jpg",
      "audio_default": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3",
      "bonus": false,
      "adfree": false,
      "early_access": false,
      "published": "2026-02-18T22:03:53.467Z",
      "updated": "2026-02-18T22:03:53.467Z"
    }
  ],
  "next_cursor": "eyJpZCI6ImU1ZjZnN2g4In0"
}

Create Item

POSThttps://api.fountain.fm/v1/feeds/{feed_id}/items

Create a DRAFT item. All fields are updated later via Update Item.

Path parameters

feed_idstringrequired

The feed to add the item to.

Responses

200The new draft item.

itemItemrequired

The new item.

Example request

curl -X POST "https://api.fountain.fm/v1/feeds/{feed_id}/items" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "item": {
    "id": "e5f6g7h8",
    "status": "DRAFT",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Load Item

GEThttps://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}

Load a single item by ID.

Path parameters

feed_idstringrequired

The feed the item belongs to.

item_idstringrequired

The item to read.

Responses

200The item.

itemItemrequired

The item.

Example request

curl -X GET "https://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "item": {
    "id": "e5f6g7h8",
    "fountain_id": "episode:id:abc123",
    "title": "The Genesis Block",
    "description": "We dig into the **first block** ever mined.",
    "season_number": 2,
    "item_number": 14,
    "links": [
      "https://citadeldispatch.com/cd141"
    ],
    "explicit": false,
    "status": "PUBLISHED",
    "image": "https://media.fountain.fm/episodes/e5f6g7h8/cover.jpg",
    "audio_default": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3",
    "bonus": false,
    "adfree": false,
    "early_access": false,
    "published": "2026-02-18T22:03:53.467Z",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Update Item

PATCHhttps://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}

Edit an item. The body is the patch: a value sets the field, null clears it, an absent key leaves it unchanged. The *_id fields attach READY uploads of the matching type: a *_paid_id upload must have been created with access: "PAID", a *_default_id with access: "DEFAULT". Attaching a video also uses its extracted audio for the same slot unless that slot's audio is already set. Enabling any paid feature needs audio_paid_id and prices a one-time product at price_usd_cents (defaults to 100 on first enable). The monetization variant is locked once the item is PUBLISHED, and a published item's required media can't be cleared.

Path parameters

feed_idstringrequired

The feed the item belongs to.

item_idstringrequired

The item to edit.

Request body

Omitted fields stay unchanged. null clears a nullable field.

titlestringoptional

Item title.

descriptionstring | nulloptional

Item description in Markdown. Max 10000 characters when converted to HTML.

season_numbernumber | nulloptional

Season number.

item_numbernumber | nulloptional

Item number within the season.

linksstring[] | nulloptional

Associated URLs. Max 3.

explicitboolean | nulloptional

Mark the item as explicit.

audio_default_idstring | nulloptional

ID of a READY ITEM_AUDIO upload for the free audio.

audio_paid_idstring | nulloptional

ID of a READY ITEM_AUDIO upload for the paid audio.

video_default_idstring | nulloptional

ID of a READY ITEM_VIDEO upload for the free video.

video_paid_idstring | nulloptional

ID of a READY ITEM_VIDEO upload for the paid video.

image_idstring | nulloptional

ID of a READY ITEM_IMAGE upload.

bonusbooleanoptional

Make the item subscriber-only. Cannot change after publishing.

adfreebooleanoptional

Offer a paid ad-free version. Not for bonus items.

early_accessbooleanoptional

Offer a paid early-access version. Not for bonus items.

early_access_daysnumberoptional

Early-access window in days.

price_usd_centsnumberoptional

Price of the paid version in USD cents.

Responses

200The updated item.

itemItemrequired

The updated item.

Example request

curl -X PATCH "https://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"The Genesis Block","audio_default_id":"6f1a2b3c-4d5e-6f70-8901-23456789abcd"}'

Request body

{
  "title": "The Genesis Block",
  "audio_default_id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd"
}

Response · 200

{
  "ok": true,
  "item": {
    "id": "e5f6g7h8",
    "fountain_id": "episode:id:abc123",
    "title": "The Genesis Block",
    "description": "We dig into the **first block** ever mined.",
    "season_number": 2,
    "item_number": 14,
    "links": [
      "https://citadeldispatch.com/cd141"
    ],
    "explicit": false,
    "status": "PUBLISHED",
    "image": "https://media.fountain.fm/episodes/e5f6g7h8/cover.jpg",
    "audio_default": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3",
    "bonus": false,
    "adfree": false,
    "early_access": false,
    "published": "2026-02-18T22:03:53.467Z",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Delete Item

DELETEhttps://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}

Soft-delete an item: its status becomes DELETED and it is removed from the feed.

Path parameters

feed_idstringrequired

The feed the item belongs to.

item_idstringrequired

The item to delete.

Responses

200The deleted item.

itemItemrequired

The deleted item.

Example request

curl -X DELETE "https://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "item": {
    "id": "e5f6g7h8",
    "fountain_id": "episode:id:abc123",
    "title": "The Genesis Block",
    "description": "We dig into the **first block** ever mined.",
    "season_number": 2,
    "item_number": 14,
    "links": [
      "https://citadeldispatch.com/cd141"
    ],
    "explicit": false,
    "status": "DELETED",
    "image": "https://media.fountain.fm/episodes/e5f6g7h8/cover.jpg",
    "audio_default": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3",
    "bonus": false,
    "adfree": false,
    "early_access": false,
    "published": "2026-02-18T22:03:53.467Z",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Publish Item

POSThttps://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}/publish

Publish an item immediately, from DRAFT or SCHEDULED: its status becomes PUBLISHED and the feed regenerates. Requires a title and default audio. No request body.

Path parameters

feed_idstringrequired

The feed the item belongs to.

item_idstringrequired

The item to publish.

Responses

200The published item.

itemItemrequired

The published item.

Example request

curl -X POST "https://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}/publish" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "item": {
    "id": "e5f6g7h8",
    "fountain_id": "episode:id:abc123",
    "title": "The Genesis Block",
    "description": "We dig into the **first block** ever mined.",
    "season_number": 2,
    "item_number": 14,
    "links": [
      "https://citadeldispatch.com/cd141"
    ],
    "explicit": false,
    "status": "PUBLISHED",
    "image": "https://media.fountain.fm/episodes/e5f6g7h8/cover.jpg",
    "audio_default": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3",
    "bonus": false,
    "adfree": false,
    "early_access": false,
    "published": "2026-02-18T22:03:53.467Z",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Schedule Item

POSThttps://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}/schedule

Schedule an item, from DRAFT or SCHEDULED: its status becomes SCHEDULED and it is released automatically at scheduled. Requires a title and default audio.

Path parameters

feed_idstringrequired

The feed the item belongs to.

item_idstringrequired

The item to schedule.

Request body

scheduledstringrequired

Publish time as a future ISO-8601 instant.

Responses

200The scheduled item.

itemItemrequired

The scheduled item.

Example request

curl -X POST "https://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}/schedule" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled":"2026-07-01T09:00:00Z"}'

Request body

{
  "scheduled": "2026-07-01T09:00:00Z"
}

Response · 200

{
  "ok": true,
  "item": {
    "id": "e5f6g7h8",
    "fountain_id": "episode:id:abc123",
    "title": "The Genesis Block",
    "description": "We dig into the **first block** ever mined.",
    "season_number": 2,
    "item_number": 14,
    "links": [
      "https://citadeldispatch.com/cd141"
    ],
    "explicit": false,
    "status": "SCHEDULED",
    "image": "https://media.fountain.fm/episodes/e5f6g7h8/cover.jpg",
    "audio_default": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3",
    "bonus": false,
    "adfree": false,
    "early_access": false,
    "published": "2026-02-18T22:03:53.467Z",
    "updated": "2026-02-18T22:03:53.467Z"
  }
}

Item Stats

GEThttps://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}/stats

Read a single item’s stats, in the same shape and with the same params as Feed Stats, scoped to one item. It takes podcast and album feeds. An artist feed has no items and returns 404 ITEM_NOT_FOUND: read each album with Feed Stats. group_by=CONTENT is a per-item breakdown and is not valid here: it returns 400 BAD_REQUEST.

Path parameters

feed_idstringrequired

The feed the item belongs to.

item_idstringrequired

The item to read stats for.

Query parameters

startstringoptional

ISO-8601 inclusive range start; also enables the previous comparison window.

endstringoptional

ISO-8601 inclusive range end.

bucketstringoptional

Bucket size for the buckets time series: DAY, WEEK or MONTH. Omit for totals only.

group_bystringoptional

Comma-separated breakdown dimensions: COUNTRY, KIND, PLATFORM, APP, ACTION, SUPPORTER.

Responses

200The item stats.

statsStatsrequired

The item stats.

Example request

curl -X GET "https://api.fountain.fm/v1/feeds/{feed_id}/items/{item_id}/stats" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "stats": {
    "rows": [
      {
        "group": {},
        "total": {
          "downloads": 1240,
          "revenue_usd": 32.5,
          "revenue_satoshis": 48210,
          "supporters": 18
        },
        "previous": {
          "downloads": 980,
          "revenue_usd": 24,
          "revenue_satoshis": 35600,
          "supporters": 14
        }
      }
    ],
    "meta": {}
  }
}