Docs/Social

Social

Connect social channels and publish posts to them.

List Social Channels

GEThttps://api.fountain.fm/v1/social/channels

List connected channels with account names, handles and images read live from each platform.

Responses

200The connected channels.

channelsSocialChannel[]required

The connected channels.

Example request

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

Response · 200

{
  "channels": [
    {
      "_id": "a1b2c3d4e5f6",
      "platform": "x",
      "status": "CONNECTED",
      "info": {
        "name": "Fountain",
        "handle": "fountain_app",
        "image": "https://pbs.twimg.com/profile_images/fountain.jpg"
      }
    }
  ]
}

Add Social Channel

POSThttps://api.fountain.fm/v1/social/channels

Open the returned url to authorize the channel. Once authorized, its status is CONNECTED and it can publish. Replaces any pending connection for the same platform.

Request body

platformSocialPlatformrequired

Platform to connect.

redirectstringoptional

Trusted URL to return to after OAuth.

Responses

200The OAuth authorization URL.

urlstringrequired

Open this URL to authorize.

Example request

curl -X POST "https://api.fountain.fm/v1/social/channels" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"x"}'

Request body

{
  "platform": "x"
}

Response · 200

{
  "url": "https://x.com/i/oauth2/authorize?response_type=code&client_id=...&state=a1b2c3d4e5f6"
}

Reconnect Social Channel

PATCHhttps://api.fountain.fm/v1/social/channels/{channel_id}

Renew expired or revoked access by opening the returned authorization url. The channel keeps its ID and platform and returns to CONNECTED after authorization.

Path parameters

channel_idstringrequired

The channel to reconnect.

Request body

reconnecttruerequired

Confirms the reconnection.

redirectstringoptional

Trusted URL to return to after OAuth.

Responses

200The OAuth authorization URL.

urlstringrequired

Open this URL to authorize.

Example request

curl -X PATCH "https://api.fountain.fm/v1/social/channels/{channel_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reconnect":true}'

Request body

{
  "reconnect": true
}

Response · 200

{
  "url": "https://x.com/i/oauth2/authorize?response_type=code&client_id=...&state=a1b2c3d4e5f6"
}

List Social Posts

GEThttps://api.fountain.fm/v1/social/posts

List draft and published posts. Filter by status, source, since, or any of them together.

Query parameters

statusSocialPostStatusoptional

Filter by status. Omit for all posts.

sourceContentIDoptional

Filter by a link in source.ids, e.g. episode:id:abc123 or show:id:xyz789.

sincestringoptional

Only return posts created at or after this ISO-8601 date or timestamp, e.g. 2026-10-01. Dates use midnight UTC.

Responses

200The posts.

postsSocialPost[]required

The posts.

Example request

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

Response · 200

{
  "posts": [
    {
      "_id": "p1q2r3s4t5u6",
      "content": {
        "context": "## Why this post\n\nBitcoin price went above $100,000, and this is generating a lot of engagement on X. The latest episode had John Doe, who discussed the effect of Bitcoin price fluctutations.",
        "title": "Bitcoin price increase",
        "text": "Bitcoin just hit $100,000. Check out my latest episode on why that matters.",
        "uploads": []
      },
      "meta": {
        "label": "Bitcoin above $100k",
        "channel": "a1b2c3d4e5f6",
        "created": "2026-06-01T12:00:00.000Z",
        "updated": "2026-06-01T12:00:00.000Z",
        "synced": "2026-06-02T12:00:00.000Z",
        "published": "2026-06-01T12:00:05.000Z",
        "status": "PUBLISHED"
      },
      "platform": {
        "type": "x",
        "id": "1789012345678901234",
        "link": "https://x.com/fountain_app/status/1789012345678901234"
      },
      "source": {
        "ids": [
          "episode:id:abc123",
          "show:id:xyz789"
        ],
        "media": "https://media.fountain.fm/episodes/abc123.mp3",
        "transcript": "the genesis block was mined in 2009",
        "ts_start": 2477.91,
        "ts_end": 2493.9
      },
      "stats": {
        "views": 1240,
        "likes": 87,
        "comments": 12
      }
    }
  ]
}

Create Social Post

POSThttps://api.fountain.fm/v1/social/posts

Create a draft on a CONNECTED channel. Omitted fields stay empty until set with Update Social Post.

With a source and no upload_id, Fountain renders a video from the source and attaches it as the post's upload. The upload is PENDING during the render, then READY or ERROR; read it with Get Upload. To use your own video, pass a READY SOCIAL_POST_VIDEO upload ID as upload_id.

Request body

channel_idstringrequired

ID of the connected channel to post to.

labelstringoptional

Internal label for the post.

titlestringoptional

Post title on the platform. YouTube only, at most 100 characters.

textstringoptional

Post text: the post on X, the description on YouTube, the caption on Instagram. At most 280 characters on X, 5000 bytes on YouTube and 2200 characters on Instagram. On X, a URL counts as 23 characters, and an emoji or a CJK character counts as 2 characters.

contextstringoptional

Context for choosing a candidate post, in Markdown.

sourceSocialPostMediaSourceoptional

Part of an episode or a YouTube video to clip. ids holds an episode:id: and its show:id:, optionally with the youtube:video: ID of the same recording, or one youtube:video: ID. Without upload_id, Fountain renders a video from it and attaches a PENDING upload that becomes READY or ERROR. A later source change keeps the video until the post is rendered again.

upload_idstringoptional

ID of a READY SOCIAL_POST_VIDEO upload, to use your own video. Only a new render replaces it. The current upload ID leaves the upload unchanged, even while PENDING.

Responses

200The created post.

postSocialPostrequired

The created post.

Example request

curl -X POST "https://api.fountain.fm/v1/social/posts" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"a1b2c3d4e5f6","label":"Bitcoin above $100k","text":"Bitcoin just went above $100,000. Here is what it means for you.","context":"## Why this post\n\nBitcoin went above $100,000 and the latest episode covers exactly that.","source":{"ids":["episode:id:abc123","show:id:xyz789"],"media":"https://media.fountain.fm/episodes/abc123.mp3","transcript":"the genesis block was mined in 2009","ts_start":2477.91,"ts_end":2493.9}}'

Request body

{
  "channel_id": "a1b2c3d4e5f6",
  "label": "Bitcoin above $100k",
  "text": "Bitcoin just went above $100,000. Here is what it means for you.",
  "context": "## Why this post\n\nBitcoin went above $100,000 and the latest episode covers exactly that.",
  "source": {
    "ids": [
      "episode:id:abc123",
      "show:id:xyz789"
    ],
    "media": "https://media.fountain.fm/episodes/abc123.mp3",
    "transcript": "the genesis block was mined in 2009",
    "ts_start": 2477.91,
    "ts_end": 2493.9
  }
}

Response · 200

{
  "post": {
    "_id": "p1q2r3s4t5u6",
    "content": {
      "context": "## Why this post\n\nBitcoin price went above $100,000, and this is generating a lot of engagement on X. The latest episode had John Doe, who discussed the effect of Bitcoin price fluctutations.",
      "title": "Bitcoin price increase",
      "text": "Bitcoin just hit $100,000. Check out my latest episode on why that matters.",
      "uploads": []
    },
    "meta": {
      "label": "Bitcoin above $100k",
      "channel": "a1b2c3d4e5f6",
      "created": "2026-06-01T12:00:00.000Z",
      "updated": "2026-06-01T12:00:00.000Z",
      "synced": "2026-06-02T12:00:00.000Z",
      "published": "2026-06-01T12:00:05.000Z",
      "status": "PUBLISHED"
    },
    "platform": {
      "type": "x",
      "id": "1789012345678901234",
      "link": "https://x.com/fountain_app/status/1789012345678901234"
    },
    "source": {
      "ids": [
        "episode:id:abc123",
        "show:id:xyz789"
      ],
      "media": "https://media.fountain.fm/episodes/abc123.mp3",
      "transcript": "the genesis block was mined in 2009",
      "ts_start": 2477.91,
      "ts_end": 2493.9
    },
    "stats": {
      "views": 1240,
      "likes": 87,
      "comments": 12
    }
  }
}

Load Social Post

GEThttps://api.fountain.fm/v1/social/posts/{post_id}

Load a social post by ID.

Path parameters

post_idstringrequired

The post to load.

Responses

200The post.

postSocialPostrequired

The post.

404Post not found.

Example request

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

Response · 200

{
  "post": {
    "_id": "p1q2r3s4t5u6",
    "content": {
      "context": "## Why this post\n\nBitcoin price went above $100,000, and this is generating a lot of engagement on X. The latest episode had John Doe, who discussed the effect of Bitcoin price fluctutations.",
      "title": "Bitcoin price increase",
      "text": "Bitcoin just hit $100,000. Check out my latest episode on why that matters.",
      "uploads": []
    },
    "meta": {
      "label": "Bitcoin above $100k",
      "channel": "a1b2c3d4e5f6",
      "created": "2026-06-01T12:00:00.000Z",
      "updated": "2026-06-01T12:00:00.000Z",
      "synced": "2026-06-02T12:00:00.000Z",
      "published": "2026-06-01T12:00:05.000Z",
      "status": "PUBLISHED"
    },
    "platform": {
      "type": "x",
      "id": "1789012345678901234",
      "link": "https://x.com/fountain_app/status/1789012345678901234"
    },
    "source": {
      "ids": [
        "episode:id:abc123",
        "show:id:xyz789"
      ],
      "media": "https://media.fountain.fm/episodes/abc123.mp3",
      "transcript": "the genesis block was mined in 2009",
      "ts_start": 2477.91,
      "ts_end": 2493.9
    },
    "stats": {
      "views": 1240,
      "likes": 87,
      "comments": 12
    }
  }
}

Update Social Post

PATCHhttps://api.fountain.fm/v1/social/posts/{post_id}

1 credit per published post

Update post content, media or publishing options. Omitted fields stay unchanged. A source change does not change the video; call Render Social Post to render the new source. To use your own video, pass a READY SOCIAL_POST_VIDEO upload ID as upload_id. Sending the current upload_id leaves the upload unchanged, even while it is PENDING. Every publish mode approves the post; SCHEDULE also sets a publish time, and NOW publishes immediately. Published, publishing and errored posts cannot be updated.

Pricing

1 credit per published post from your project credits. Charged once per post when first scheduled or published. Drafts are free; each channel is a separate post.

Path parameters

post_idstringrequired

The post to update.

Request body

Omitted fields stay unchanged.

labelstringoptional

Internal label for the post.

titlestringoptional

Post title on the platform. YouTube only, at most 100 characters.

textstringoptional

contextstringoptional

Context for choosing a candidate post, in Markdown.

sourceSocialPostMediaSourceoptional

upload_idstringoptional

ID of a READY SOCIAL_POST_VIDEO upload, to use your own video. Only a new render replaces it. The current upload ID leaves the upload unchanged, even while PENDING.

publishobjectoptional

Approve, schedule or publish the post now.

mode'APPROVED' | 'NOW' | 'SCHEDULE'required

Approve the post, schedule it or publish it now.

timestring | numberoptional

Publish time as an ISO-8601 instant. For SCHEDULE mode.

Responses

200The updated post.

postSocialPostrequired

The updated post.

400Post is published, publishing or in error.

404Post not found.

Example request

curl -X PATCH "https://api.fountain.fm/v1/social/posts/{post_id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated title","text":"Updated caption","publish":{"mode":"APPROVED"}}'

Request body

{
  "title": "Updated title",
  "text": "Updated caption",
  "publish": {
    "mode": "APPROVED"
  }
}

Response · 200

{
  "post": {
    "_id": "p1q2r3s4t5u6",
    "content": {
      "context": "## Why this post\n\nBitcoin price went above $100,000, and this is generating a lot of engagement on X. The latest episode had John Doe, who discussed the effect of Bitcoin price fluctutations.",
      "title": "Bitcoin price increase",
      "text": "Bitcoin just hit $100,000. Check out my latest episode on why that matters.",
      "uploads": []
    },
    "meta": {
      "label": "Bitcoin above $100k",
      "channel": "a1b2c3d4e5f6",
      "created": "2026-06-01T12:00:00.000Z",
      "updated": "2026-06-01T12:00:00.000Z",
      "synced": "2026-06-02T12:00:00.000Z",
      "published": "2026-06-01T12:00:05.000Z",
      "status": "PUBLISHED"
    },
    "platform": {
      "type": "x",
      "id": "1789012345678901234",
      "link": "https://x.com/fountain_app/status/1789012345678901234"
    },
    "source": {
      "ids": [
        "episode:id:abc123",
        "show:id:xyz789"
      ],
      "media": "https://media.fountain.fm/episodes/abc123.mp3",
      "transcript": "the genesis block was mined in 2009",
      "ts_start": 2477.91,
      "ts_end": 2493.9
    },
    "stats": {
      "views": 1240,
      "likes": 87,
      "comments": 12
    }
  }
}

Render Social Post

POSThttps://api.fountain.fm/v1/social/posts/{post_id}/render

Render the post's video from its source, to change the look, retry a failed render or use new Brand preferences. Describe the change in prompt, e.g. "bigger captions".

The new video replaces the post's video, also an upload of your own, and the rendered video of every unpublished post that shares it. The returned upload is PENDING until the render ends; read it with Get Upload. A post in ERROR goes back to DRAFT.

Path parameters

post_idstringrequired

The post to render.

Request body

promptstringoptional

How the new render should look, such as bigger captions or a different layout.

Responses

200The post and the new upload.

postSocialPostrequired

The post.

mediaMediarequired

The upload of the new render.

400The post has no `source`, or is published or publishing.

403The key is not an admin or editor of the project.

404Post not found.

Example request

curl -X POST "https://api.fountain.fm/v1/social/posts/{post_id}/render" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Bigger captions, and speed it up to 1.1x"}'

Request body

{
  "prompt": "Bigger captions, and speed it up to 1.1x"
}

Response · 200

{
  "post": {
    "_id": "p1q2r3s4t5u6",
    "content": {
      "context": "## Why this post\n\nBitcoin price went above $100,000, and this is generating a lot of engagement on X. The latest episode had John Doe, who discussed the effect of Bitcoin price fluctutations.",
      "title": "Bitcoin price increase",
      "text": "Bitcoin just hit $100,000. Check out my latest episode on why that matters.",
      "uploads": []
    },
    "meta": {
      "label": "Bitcoin above $100k",
      "channel": "a1b2c3d4e5f6",
      "created": "2026-06-01T12:00:00.000Z",
      "updated": "2026-06-01T12:00:00.000Z",
      "synced": "2026-06-02T12:00:00.000Z",
      "published": "2026-06-01T12:00:05.000Z",
      "status": "PUBLISHED"
    },
    "platform": {
      "type": "x",
      "id": "1789012345678901234",
      "link": "https://x.com/fountain_app/status/1789012345678901234"
    },
    "source": {
      "ids": [
        "episode:id:abc123",
        "show:id:xyz789"
      ],
      "media": "https://media.fountain.fm/episodes/abc123.mp3",
      "transcript": "the genesis block was mined in 2009",
      "ts_start": 2477.91,
      "ts_end": 2493.9
    },
    "stats": {
      "views": 1240,
      "likes": 87,
      "comments": 12
    }
  },
  "media": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "kind": "SOCIAL_POST_VIDEO",
    "status": "PENDING"
  }
}

Delete Social Post

DELETEhttps://api.fountain.fm/v1/social/posts/{post_id}

Path parameters

post_idstringrequired

The post to delete.

Responses

200Post deleted.