API reference

Generates a caption, hashtags, and a cover graphic for a topic/platform, without saving anything - this is what the Composer page calls as you type and hit "Generate post". Uses the workspace's own AI key if one is set in Settings, otherwise the deployment-wide key, otherwise the built-in mock engine.

{ "platform": "instagram" | "twitter" | "linkedin" | "facebook" | "tiktok",
  "topic": "what the post is about", "tone"?: "optional extra tone guidance" }

{ "ok": true, "platform": "...", "topic": "...", "caption": "...", "hashtags": "...",
  "imageSvg": "", "engine": "mock" | "gemini" | "claude" }

Saves a post - either as a draft or, if scheduledAt is set, scheduled for later. Typically called right after /api/posts/generate with that response's caption/hashtags/imageSvg, but any of those fields can be hand-edited first.

{ "platform": "...", "caption": "...", "topic"?: "...", "hashtags"?: "...",
  "imageSvg"?: "", "engine"?: "mock" | "gemini" | "claude",
  "campaignId"?: "...", "scheduledAt"?: "2026-09-10T14:00:00.000Z" }

{ "ok": true, "post": { ...the saved post row... } }

Manually marks a post as posted, with no real publish attempt - the fallback for platforms without a real connector (Instagram, Facebook, TikTok), or for any platform you posted to by hand.

(none)

{ "ok": true, "post": { ... } }

AI-brainstorms 6 on-theme post ideas for a campaign, based on its name and goal. Used by the "Generate 6 ideas" button on a campaign's detail page.

(none)

{ "ok": true, "ideas": [ "idea one", "idea two", ... ], "engine": "mock" | "gemini" | "claude" }

Turns one brainstormed idea line straight into a fully generated, saved draft post tied to the campaign (generates caption + hashtags + cover graphic and saves it in one step) - the "+ Turn into post" button.

{ "idea": "the idea text from the ideas list", "platform"?: "instagram" | "twitter" | "linkedin" | ... }

{ "ok": true, "post": { ...the saved post row... } }

Publishes one post for real, right now, through whatever platform connector applies - the same path the in-process scheduler uses for a due scheduled post. Always writes the outcome back onto the post (a real platform URL on success, a clear error on failure) before responding.

(none)

{ "ok": true, "post": { ...updated post, status "posted", platform_post_url set... } }

Saves a developer app's Client ID/Secret for Twitter/X or LinkedIn (the app credentials Bloom uses to start that platform's OAuth flow) - step one of connecting, before /oauth/:platform/start.

{ "clientId": "...", "clientSecret"?: "..." }  (:platform is "twitter" or "linkedin")

{ "ok": true, "connection": { ...the platform_connections row... } }

Connects a Mastodon account directly with an instance URL + personal access token (no OAuth redirect needed - Mastodon connects in one call, unlike Twitter/LinkedIn).

{ "instanceUrl": "https://mastodon.social", "accessToken": "..." }

{ "ok": true, "connection": { ...the platform_connections row, status "connected"... } }

Disconnects a platform - clears its stored tokens and account info and sets it back to "disconnected". Posts already published through it are unaffected.

(none)

{ "ok": true, "connection": { ...the platform_connections row, status "disconnected"... } }

Builds a state + PKCE code-verifier/challenge pair, stores them on the workspace's connection row, and redirects (302) to Twitter/X's OAuth 2.0 authorize URL.

(none - browser navigation, not fetched)

302 redirect to Twitter/X.

Twitter/X redirects the browser back here with a code and state. Verifies state matches, exchanges the code (with the stored PKCE verifier) for an access token, fetches the connected account's handle/URL, and marks the connection "connected".

(none - query params `code`, `state`, or `error` set by Twitter/X)

302 redirect to /dashboard/settings?connected=twitter.

Same idea as the Twitter start route (state only, no PKCE - LinkedIn uses plain Authorization Code) - redirects (302) to LinkedIn's OAuth consent screen.

(none - browser navigation, not fetched)

302 redirect to LinkedIn.

LinkedIn redirects the browser back here with a code and state. Verifies state, exchanges the code for an access token, fetches the connected account's profile URN, and marks the connection "connected".

(none - query params `code`, `state`, or `error` set by LinkedIn)

302 redirect to /dashboard/settings?connected=linkedin.

Starts a subscription upgrade/downgrade. Redirects (302) to a real Stripe Checkout page when Stripe is configured (STRIPE_SECRET_KEY + a price ID for the plan); otherwise falls back to updating the stored plan directly ("demo mode") and redirects to Settings. Session-authenticated, form-encoded (not JSON) since it's posted by a real HTML form.

plan=starter | growth | agency (form-encoded)

302 redirect (to Stripe Checkout, or back to Settings in demo mode).

Stripe redirects the browser here after a successful Checkout. Does a best-effort immediate sync of the new plan/subscription so the UI reflects it right away, without waiting on the webhook round-trip (the webhook below is still the real source of truth).

(none - query param `session_id` set by Stripe)

302 redirect to /dashboard/settings?saved=1&billing_success=1.

Redirects to a real Stripe Billing Portal session for the current workspace (requires Stripe to be configured and the workspace to already have a Stripe customer).

(none)

302 redirect to Stripe, or back to Settings with an error.

Stripe calls this directly - not session-authenticated, verified instead via the Stripe-Signature header (HMAC-SHA256, requires STRIPE_WEBHOOK_SECRET). Handles checkout.session.completed, customer.subscription.updated/created, and customer.subscription.deleted to keep each workspace's plan/subscription_status/current_period_end in sync.

Raw Stripe event JSON (sent by Stripe, not by you).

{ "received": true } on success, or { "error": "..." } with 400 on a bad/missing signature.