Docs/Publishing

Publishing

Manage hosted feeds and items. Feeds represent shows; items represent episodes.

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 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}

Set fields with values, clear them with null, or omit them to leave them unchanged. For image_id, use a READY FEED_IMAGE upload from Start Upload. Published feeds require title, author, description, image_id and categories; these cannot 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

Get downloads and, for published feeds, payments. Artist downloads come from their albums. group_by coverage: CONTENT and APP include both; COUNTRY, KIND and PLATFORM include downloads only (revenue and supporters are 0); ACTION and SUPPORTER include payments only (downloads are 0). group.content is an item ID, or an album feed ID for artists. Deleted items and livestreams count toward totals but are omitted from breakdowns.

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 items newest first, up to 100 per page. Pass next_cursor as cursor for the next page; it is absent on 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, then set its fields with 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 an 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}

Set fields with values, clear them with null, or omit them to leave them unchanged. Media IDs must reference READY uploads of the matching type and access: PAID for *_paid_id, DEFAULT for *_default_id. Video fills the matching audio slot with extracted audio if that slot is empty. Paid features require audio_paid_id. The one-time price is price_usd_cents, defaulting to 100 on first enable. Published items cannot change monetization variant or clear required media.

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}

Set the item’s status to DELETED and remove it 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 a DRAFT or SCHEDULED item and regenerate the feed. 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

Set a DRAFT or SCHEDULED item to SCHEDULED for automatic release 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

Get item stats using the response format and parameters of Feed Stats. Supports podcast and album feeds. Artist feeds return 404 ITEM_NOT_FOUND; use Feed Stats for each album. group_by=CONTENT 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": {}
  }
}