Docs/Social

Social

Connect social channels and publish posts to them.

List Social Channels

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

List every social channel connected to your project. Each channel also carries the account name, handle and image, read live from the 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

Begin the OAuth flow for a platform. Returns an authorization url - open it to grant access; on completion the channel becomes CONNECTED and can be used to publish posts. Any pending connection for the same platform is replaced.

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/{id}

Reconnect a channel whose access has expired or been revoked. Returns a fresh authorization url, just like Add Social Channel. The channel keeps its id and platform; on completion it is CONNECTED again.

Path parameters

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/{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 every social post created through your project, drafts and published alike. Pass status to filter to a single lifecycle state, and source to filter to the content a post was cut from. Both can be combined.

Query parameters

statusSocialPostStatusoptional

Return only posts in this lifecycle state. Omit for every post.

sourceContentIDoptional

Return only posts whose source.ids contains this link, e.g. episode:id:abc123 or show:id:xyz789.

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": {
        "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"
      },
      "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 post on a CONNECTED channel. Omitted fields stay empty until you set them via Update Social Post. Pass a finalized SOCIAL_POST_VIDEO upload id as upload_id to attach media.

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.

contextstringoptional

Context for choosing a candidate post, in Markdown.

sourceSocialPostMediaSourceoptional

Source media for the post. For an episode, ids must include both the episode:id: and show:id: links.

upload_idstringoptional

ID of a COMPLETED SOCIAL_POST_VIDEO upload.

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": {
      "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"
    },
    "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/{id}

Load a social post by its id.

Path parameters

idstringrequired

The post to load.

Responses

200The post.

postSocialPostrequired

The post.

404No post with that id exists.

Example request

curl -X GET "https://api.fountain.fm/v1/social/posts/{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": {
      "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"
    },
    "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/{id}

1 credit per published post

Update a post’s title, text, context, source, or attached media, and set its publish option. Every field is optional. Omit one to leave it unchanged. Omit upload_id to keep the existing media; pass a new finalized SOCIAL_POST_VIDEO upload id to replace it. publish drives the lifecycle: any option approves the post, SCHEDULE also gives it a publish time, and NOW publishes it right away (see SocialPostPublishMode). Published, publishing, and errored posts cannot be updated.

Pricing

This endpoint is metered: it costs 1 credit per published post, drawn from your project credits. Charged when the post goes out, so a draft you never approve costs nothing. A clip on two channels is two posts.

Path parameters

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

Post text: the post on X, the description on YouTube, the caption on Instagram.

contextstringoptional

Context for choosing a candidate post, in Markdown.

sourceSocialPostMediaSourceoptional

Source media for the post. For an episode, ids must include both the episode:id: and show:id: links.

upload_idstringoptional

ID of a COMPLETED SOCIAL_POST_VIDEO upload.

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.

400The post is already published, already publishing, or in error.

404No post with that id exists.

Example request

curl -X PATCH "https://api.fountain.fm/v1/social/posts/{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": {
      "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"
    },
    "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
    }
  }
}

Delete Social Post

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

Path parameters

idstringrequired

The post to delete.

Responses

200The post has been deleted succesfully.