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 COMPLETED 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 a feed’s download stats, plus payment stats once it is published. 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; 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 COMPLETED ITEM_AUDIO upload for the free audio.

audio_paid_idstring | nulloptional

ID of a COMPLETED ITEM_AUDIO upload for the paid audio.

video_default_idstring | nulloptional

ID of a COMPLETED ITEM_VIDEO upload for the free video.

video_paid_idstring | nulloptional

ID of a COMPLETED ITEM_VIDEO upload for the paid video.

image_idstring | nulloptional

ID of a COMPLETED 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. group_by=CONTENT is a per-episode 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": {}
  }
}