Social
Connect social channels and publish posts to them.
List Social Channels
List connected channels with account names, handles and images read live from each platform.
Responses
200The connected channels.The connected channels.
curl -X GET "https://api.fountain.fm/v1/social/channels" \
-H "Authorization: Bearer $FOUNTAIN_API_KEY"{
"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
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
Platform to connect.
redirectstringoptionalTrusted URL to return to after OAuth.
Responses
200The OAuth authorization URL.urlstringrequiredOpen this URL to authorize.
curl -X POST "https://api.fountain.fm/v1/social/channels" \
-H "Authorization: Bearer $FOUNTAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"x"}'{
"platform": "x"
}{
"url": "https://x.com/i/oauth2/authorize?response_type=code&client_id=...&state=a1b2c3d4e5f6"
}Reconnect Social Channel
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_idstringrequiredThe channel to reconnect.
Request body
reconnecttruerequiredConfirms the reconnection.
redirectstringoptionalTrusted URL to return to after OAuth.
Responses
200The OAuth authorization URL.urlstringrequiredOpen this URL to authorize.
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}'{
"reconnect": true
}{
"url": "https://x.com/i/oauth2/authorize?response_type=code&client_id=...&state=a1b2c3d4e5f6"
}List Social Posts
List draft and published posts. Filter by status, source, since, or any of them together.
Query parameters
Filter by status. Omit for all posts.
Filter by a link in source.ids, e.g. episode:id:abc123 or show:id:xyz789.
sincestringoptionalOnly return posts created at or after this ISO-8601 date or timestamp, e.g. 2026-10-01. Dates use midnight UTC.
Responses
200The posts.The posts.
curl -X GET "https://api.fountain.fm/v1/social/posts" \
-H "Authorization: Bearer $FOUNTAIN_API_KEY"{
"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
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_idstringrequiredID of the connected channel to post to.
labelstringoptionalInternal label for the post.
titlestringoptionalPost title on the platform. YouTube only, at most 100 characters.
textstringoptionalPost 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.
contextstringoptionalContext for choosing a candidate post, in Markdown.
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_idstringoptionalID 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.The created post.
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}}'{
"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
}
}{
"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
Load a social post by ID.
Path parameters
post_idstringrequiredThe post to load.
Responses
200The post.The post.
404Post not found.curl -X GET "https://api.fountain.fm/v1/social/posts/{post_id}" \
-H "Authorization: Bearer $FOUNTAIN_API_KEY"{
"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
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_idstringrequiredThe post to update.
Request body
Omitted fields stay unchanged.
labelstringoptionalInternal label for the post.
titlestringoptionalPost title on the platform. YouTube only, at most 100 characters.
textstringoptionalPost 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.
contextstringoptionalContext for choosing a candidate post, in Markdown.
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_idstringoptionalID 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.
publishobjectoptionalApprove, schedule or publish the post now.
mode'APPROVED' | 'NOW' | 'SCHEDULE'requiredApprove the post, schedule it or publish it now.
timestring | numberoptionalPublish time as an ISO-8601 instant. For SCHEDULE mode.
Responses
200The updated post.The updated post.
400Post is published, publishing or in error.404Post not found.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"}}'{
"title": "Updated title",
"text": "Updated caption",
"publish": {
"mode": "APPROVED"
}
}{
"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
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_idstringrequiredThe post to render.
Request body
promptstringoptionalHow the new render should look, such as bigger captions or a different layout.
Responses
200The post and the new upload.The post.
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.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"}'{
"prompt": "Bigger captions, and speed it up to 1.1x"
}{
"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
Path parameters
post_idstringrequiredThe post to delete.
Responses
200Post deleted.curl -X DELETE "https://api.fountain.fm/v1/social/posts/{post_id}" \
-H "Authorization: Bearer $FOUNTAIN_API_KEY"