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

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 draft and published posts. Filter by status, source, or both.

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.

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 on a CONNECTED channel. Omitted fields stay empty until set with Update Social Post. Attach media by passing a finalized 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

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

upload_idstringoptional

ID of a READY 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 ID.

Path parameters

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/{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 post content, media or publishing options. Omitted fields stay unchanged. To replace media, pass a finalized SOCIAL_POST_VIDEO upload ID as upload_id. 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

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

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

upload_idstringoptional

ID of a READY 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.

400Post is published, publishing or in error.

404Post not found.

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

200Post deleted.