BetterPost

Adds a source to a project and fetches it immediately (bounded by a few seconds), returning storiesAdded so the next generate_content can use it; if it is still fetching it returns fetched:false with a note. Doubles as manual source import: paste any URL (RSS/Atom feed, article, or a page, profile, or post on a supported platform) and leave type as autodetect, or create a recurring keyword search by setting value to the search terms and type to a search kind (see type).

Manually imports a story you read about from its URL (pinned relevance, flagged is_manual) so generation can draw on it.

Create a content project. Slow, one-shot: infers config (criteria, industry, tone), discovers sources, and gathers/ranks an initial set of timely stories. Best called after the inferred audience, description, and tone have been confirmed with the user, since the config shapes everything downstream.

Delete a piece of content and its hosted images.

Permanently deletes a project and everything in it — its sources, stories, and content. Cannot be undone.

Transform an existing piece into another format (e.g. newsletter → tweet). No fetching; reuses the source stories and topic.

Broadens a project's coverage: expands the relevance criteria (when needed), finds more sources across news, the web, and the relevant social platforms, and fetches them inline. Applies on a topic_unavailable, no_stories, or low-coverage signal. May return warming: true with retryAfterMs (~60s), meaning the newly gathered stories are still landing. An out-of-scope focus requires confirmedByUser: true; without it, it returns a confirmation_required error. No credits are charged.

Generate a new piece of content for a project from its timely, relevant stories. Fast in steady state. Charges credits on success only. If you pass a topic the project has no stories about, this returns a topic_unavailable error (no charge) carrying an inScope flag and next steps — it never silently writes an off-topic piece.

Fetch one piece of content in full.

Returns one project with its relevance criteria (each with an id, so a criterion can be targeted for removal via betterpost_update_project).

Returns a project's per-content-type settings (wordLimit and additionalInstructions for each channel).

Your credit balance, freeze state, and recent spend.

Hides a story so generation ignores it. Reversible with unhide_story.

Rewrite existing text into BetterPost's readable, human voice. Preserves the meaning, facts, links, and format; returns the rewritten text plus short notes on what changed. Pass projectId to write in that project's tone and instructions, type to apply a channel's style, or tone to set the voice directly.

List a project's content (summaries + shareable publicUrl links).

Returns your projects, each with its relevance criteria (with ids) that define what counts as on-topic.

Returns one slimmed page of a project's sources plus project-wide total and counts (ok/failing/disabled/pending, and byType). Page with limit (default 50) and offset, following the returned nextOffset until it is null.

Returns a project's gathered stories, each with title, url, summary, relevancy, publicationDate, and isManual/isHidden flags. Pass includeHidden to include hidden ones.

Removes a source from a project. Its already-gathered stories stay; the source is no longer fetched.

Clusters a project's current stories into a few candidate angles — each with a label, how many stories back it, and example headlines — and warms the project (gathers and ranks fresh stories) in the process. Returns topics you can offer the user before generate_content.

Unhides a previously hidden story so generation can use it again.

Updates a project's title, audience, description, tone, freshness window, timezone, or relevance criteria, and returns the updated project with its criteria. Changing title/audience/description re-derives the relevance criteria (replace-all), which broadens or narrows what counts as on-topic. To edit criteria incrementally instead, pass patch.addCriteria (texts to append) and/or patch.removeCriteria (criterion ids from get_project/list_projects). Dates default to US Eastern unless a timezone (an IANA name like "America/New_York") is set.

Patches one content type's wordLimit and/or additionalInstructions (free-form writing guidance for that type; pass an empty string to clear it). Project-wide preferences (title/audience/tone, project-wide additionalInstructions) live on betterpost_update_project.