fopost

Official Python SDK for the FoPost API. Schedule and publish to +30 social platforms from your code.

pip install fopost

Requires Python 3.10 or newer. Built on httpx and pydantic v2, fully typed.

0.x release. The public API is still settling and minor versions may contain breaking changes. Pin an exact version if that matters to you.

Quick start

from fopost import Fopost

client = Fopost(api_key="fp_...")  # or set FOPOST_API_KEY

workspace = client.workspaces.list()[0]
accounts = client.accounts.list(workspace_id=workspace.id)

post = client.posts.create(
    workspace_id=workspace.id,
    content="Hello from Python",
    accounts=[a.id for a in accounts],
)

client.posts.publish(post.id)

content takes a string for a single block, or a list for a thread:

client.posts.create(
    workspace_id=workspace.id,
    content=[
        "First post in the thread",
        {
            "text": "Second one, with an image",
            "media": [
                {"type": "image", "name": "chart.png", "url": "https://.../chart.png"},
            ],
        },
    ],
    accounts=[a.id for a in accounts],
)

Scheduling

status is "draft" or "scheduled"; a scheduled post needs schedule_at. To send something out now, create it and call publish.

from datetime import datetime, timezone

client.posts.create(
    workspace_id=workspace.id,
    status="scheduled",
    schedule_at=datetime(2026, 9, 1, 10, 0, tzinfo=timezone.utc),
    content="Scheduled with the SDK",
    accounts=[accounts[0].id],
)

Pagination

posts.list returns one page and iterates over its items directly. posts.iter walks every page for you:

page = client.posts.list(workspace_id=workspace.id, status="published", per_page=50)
print(f"{page.meta.total} published posts")
for post in page:
    print(post.id, post.status)

# Every post, one page fetched at a time
for post in client.posts.iter(workspace_id=workspace.id):
    print(post.id)

# Or page by page, when you want the meta
for page in client.posts.iter_pages(workspace_id=workspace.id):
    print(page.meta.current_page, len(page))

AI features

balance = client.ai.credits()
print(f"{balance.credits_remaining} of {balance.credits_total} credits left")

result = client.ai.generate_caption(
    current_caption="shipping a new feature",
    platforms=["twitter", "linkedin"],
)
print(result.caption)

rewrite and repurpose_url are wired the same way:

rewrites = client.ai.rewrite(
    content="Long article-style draft...",
    platforms=["twitter", "linkedin", "bluesky"],
)
for variant in rewrites.results:
    print(variant.platform, variant.content)

repurposed = client.ai.repurpose_url(
    url="https://example.com/blog/post",
    platforms=["twitter", "linkedin", "bluesky", "threads"],
)

API keys reach credits and generate_caption. rewrite and repurpose_url currently require a signed-in dashboard session and answer 401 to an API key. They are here so the surface is complete once the server opens them up.

Blog

client.blog plans keywords, writes articles and publishes them to a website. A post goes to a social network; an article goes to a website. suggest_seeds proposes search terms from the blog goal and topics, plan_keywords researches them into suggested keywords, and setting a keyword's status to planned puts it on the calendar. A draft is submitted for approval before it can be published.

article = client.blog.request_article(
    workspace.id,
    keyword="best trail running shoes",
    instructions="Mention the return policy.",
)
print(article.status)  # "queued"; it becomes a draft once written

for draft in client.blog.list_articles(workspace.id, status="draft"):
    client.blog.submit_article(workspace.id, draft.id)
    client.blog.publish_article(workspace.id, draft.id)

With the Website target, every published article is POSTed to your website_url as a signed webhook. verify_webhook checks the signature over the raw body and returns the envelope:

from fopost import ArticlePublishedPayload, verify_webhook


@app.post("/webhooks/fopost")
async def inbound(request: Request) -> Response:
    secret = os.environ["FOPOST_WEBHOOK_SECRET"]
    event = verify_webhook(await request.body(), request.headers, secret)
    if event.event == "article.published":
        article = ArticlePublishedPayload.model_validate(event.data)
        save_article(article.slug, article.body_html)
    return Response(status_code=204)

The secret is returned once, when update_settings(..., website_url=...) first saves the URL; rotate_website_secret issues a new one. A forged, stale or unsigned delivery raises WebhookVerificationError with a code.

Analytics

# How long a post keeps earning, from the repeated readings of each post
decay = client.analytics.decay(days=30)
print(decay.half_life_bucket)  # e.g. "1h_3h"

# Whether posting more earned more
cadence = client.analytics.frequency(days=90)
print(cadence.best.label if cadence.best else None)  # e.g. "3-5 a week"

# Every reading held for one post, with what moved between them
timeline = client.analytics.timeline(post.id)

# Mirror the metrics into your own store, without refetching everything
cursor = None
while True:
    page = client.analytics.changes(since=cursor)
    save(page.changes)
    if not page.has_more or page.cursor is None:
        break
    cursor = page.cursor.isoformat()

# Refresh one post now instead of waiting for the next collection run
client.analytics.collect_post(post.id)

# Posts on the account that never went out through FoPost
for native in client.analytics.native_posts(accounts[0].id):
    print(native.permalink, native.metrics.engagements)

A post is addressed by its FoPost id or by its permalink, so a post made by hand on the network works the same way::

client.analytics.timeline("https://x.com/acme/status/1")

Direct uploads

upload_direct presigns an upload slot, PUTs the bytes straight to storage, and registers the result as a library item:

with open("chart.png", "rb") as f:
    item = client.media.upload_direct(
        workspace_id=workspace.id,
        filename="chart.png",
        mime_type="image/png",
        data=f.read(),
    )
print(item.id, item.preview_url)

presign and complete are the two halves, for when you want to send the bytes yourself. Both take the optional folder_id, origin, brand_role, brand_voice_id and person_consent fields the library accepts.

Upload limits

media.limits reports what the account may upload. max_file_bytes is the ceiling for any route (it grows with the number of connected accounts, or with the Large Uploads add-on); multipart_max_file_bytes is the most one multipart request may carry per file, above which a file needs upload_direct:

limits = client.media.limits(workspace_id=workspace.id)
print(limits.max_file_bytes, limits.multipart_max_file_bytes, limits.next_tier)

A file over the ceiling raises FileTooLargeError (HTTP 413, error == "file_too_large") with max_file_bytes, file_bytes and upgrade_url readable on the error.

Files on posts

posts.create and posts.update take files: paths, open binary files, or (filename, bytes, mime_type) tuples. They are stored in the workspace library and attached to the first content block:

post = client.posts.create(
    workspace_id=workspace.id,
    content="Launch day",
    accounts=[a.id for a in accounts],
    files=["launch.png", ("clip.mp4", clip_bytes, "video/mp4")],
)

The SDK picks the route: when every file fits in a multipart request it sends one, and otherwise it uploads each file directly and attaches the results before sending the post. On update with no content, the files are appended to the post's first block.

Configuration

Fopost(
    api_key="fp_...",  # or FOPOST_API_KEY
    base_url="https://api.fopost.com/v1",  # override for a dev server
    timeout=30.0,  # seconds, or an httpx.Timeout
    max_retries=3,  # total attempts on a 429
    http_client=my_httpx_client,  # bring your own transport
)

The client is a context manager, and closes its transport on exit:

with Fopost() as client:
    client.posts.list(workspace_id=workspace.id)

A 429 is retried automatically, waiting for the interval the API asks for in Retry-After (delta-seconds or an HTTP date, capped at 60s). max_retries counts total attempts, so the default of 3 means two retries.

Error handling

Every non-2xx response raises FopostError or one of its subclasses, carrying the API's status, code, and message.

from fopost import Fopost, FopostError, PaymentRequiredError, RateLimitError

try:
    client.posts.publish("9b2f6c1e-...")
except PaymentRequiredError as err:
    print(f"Out of credits — upgrade at {err.upgrade_url}")
except RateLimitError as err:
    print(f"Rate limited, retry in {err.retry_after}s")
except FopostError as err:
    print(f"API {err.status} ({err.code}): {err.message}")

Resources

For an endpoint the SDK does not wrap yet, client.request sends an authenticated call and hands back the decoded body:

client.request("GET", "/analytics/summary", params={"workspace_id": workspace.id})

Chat adapter

fopost.chat_adapter wraps the inbox conversation and reply endpoints in a send/receive interface, so a chatbot framework can treat FoPost as one channel across every network that carries direct messages.

from fopost import Fopost
from fopost.chat_adapter import ChatAdapter

chat = ChatAdapter(
    Fopost(api_key=os.environ["FOPOST_API_KEY"]),
    workspace_id=workspace_id,
    webhook_secret=os.environ["FOPOST_WEBHOOK_SECRET"],
)

Inbound is the inbox.message_received webhook. Subscribe an endpoint to it in FoPost, then hand the raw body and the request headers to parse_webhook. It verifies the signature, refuses a replay, and returns the event; the event carries ids only, so receive_one reads the text back:

@app.post("/webhooks/fopost")
async def inbound(request: Request) -> Response:
    event = chat.parse_webhook(await request.body(), request.headers)
    message = chat.receive_one(event)
    if message is None:
        return Response(status_code=204)

    chat.typing(message.conversation_id, message.account_id)
    chat.send(reply_to=message.id, text=your_bot(message.text))
    chat.mark_read(message)
    return Response(status_code=204)

No webhook? receive() polls the same thing:

for message in chat.receive():
    chat.send(reply_to=message.id, text=your_bot(message.text))
    chat.mark_read(message)

Outbound takes one of three shapes. Reply to a message, reply into a thread, or open one by handle:

chat.send(reply_to=message.id, text="On it.")
chat.send(conversation_id="conv_...", text="Still here.")
chat.send(account_id="acc_...", handle="samrivera", text="Following up.")

Sending needs the publish scope on top of inbox. Every failure is a ChatAdapterError with a code (invalid_signature, stale_delivery, unexpected_event, unsupported_target, and the rest) or the usual FopostError from the API.

Example

examples/create_post.py creates a post against a running API:

export FOPOST_API_KEY=fp_...
export FOPOST_BASE_URL=http://localhost:8080/v1
python examples/create_post.py "Hello from the Python SDK" --publish

Contributing

Issues and pull requests are welcome at fopost/fopost-python.

uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy

License

MIT

Questions or a problem: fopost.com/contact.

Google Ads

Campaigns, ad groups, ads, audiences and insights are on client.ads and dispatch by connection. What only Google has is under client.ads.google:

keywords = client.ads.google.keywords(
    connection_id="c4d5e6f7-…",
    customer_id="1234567890",
)

client.ads.google.create_keyword(
    workspace_id="7d2b8c11-…",
    connection_id="c4d5e6f7-…",
    customer_id="1234567890",
    ad_group_id="1234567890~adGroup~77",
    text="running shoes",
    match_type="EXACT",
)

Also keyword_ideas, keyword_metrics, search_terms, bid_strategies, ad_schedule and set_ad_schedule, the negative keyword lists, assets and asset_groups, local_services_leads, the conversion methods, and query for a raw read-only GAQL SELECT. Changes need the publish scope as well as ads; customer_id has to name an account the connection's grant reaches.