Python SDK
The official Python client for the FoPost API.
fopost is the official Python client. It is built on httpx and pydantic v2, fully typed, and needs Python 3.10 or newer.
pip install fopostThis is a 0.x release. The surface is still settling and a minor version may break something. Pin an exact version if that matters to you.
Published on PyPI. Source and issues: github.com/fopost/fopost-python. MIT licensed.
Quick start
from fopost import Fopost
client = Fopost() # reads FOPOST_API_KEY, or pass 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)publish returns once delivery is queued, not once it is live. Read client.posts.deliveries(post.id) or subscribe to webhooks for the result.
Threads and media
content takes a string for a single post, 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],
)Schedule instead
client.posts.create(
workspace_id=workspace.id,
content="Doors open Monday.",
accounts=[accounts[0].id],
status="scheduled",
schedule_at="2026-09-02T09:00:00Z",
)Times are UTC.
What is on the client
| Namespace | Methods |
|---|---|
client.posts | list, iter, iter_pages, get, create, update, delete, publish, cancel, retry, preflight, deliveries |
client.accounts | list, get, health |
client.workspaces | list, get |
client.labels | list |
client.ai | credits, generate_caption, rewrite, repurpose_url |
client.inbox | list, threads, conversations, unread_count, accounts, platforms, mark_thread_read, refresh, update, reply, hide, unhide, delete, like, unlike, pin, unpin, react, edit_comment, start_conversation, set_typing, list_approvals, approve_reply, reject_reply |
client.ads | list, external, boostable, connections, sources, authorize_meta, delete_connection, boost, create, refresh, set_status, delete, audiences, create_audience, search_targeting, lead_forms, create_lead_form, leads |
client.ads.boost, create, set_status and delete spend money, so they need the publish scope as well as ads.
client.posts.iter() walks every page for you, so you do not hand-roll a
pagination loop to sweep a workspace.
On client.ai, only credits and generate_caption work with an API key
today. rewrite and repurpose_url reach endpoints that require a dashboard
session and will answer 401. Use the composer for those until a later
release.
Errors
Failed requests raise a typed exception carrying the status and the API's
error code. A 402 means the usage credit ran out (add a payment method) and should not be retried; a
429 carries the seconds to wait.
Chat adapter
fopost.chat_adapter wraps the inbox conversation and reply endpoints in a send/receive
interface, for plugging FoPost into a chatbot framework:
from fopost.chat_adapter import ChatAdapter
chat = ChatAdapter(client, workspace_id=workspace_id, webhook_secret=secret)
event = chat.parse_webhook(raw_body, request.headers)
message = chat.receive_one(event)
if message:
chat.send(reply_to=message.id, text="On it.")Full walkthrough: chat adapter.
Next
Related documentation
- SDKs & Integrations
Official FoPost clients for TypeScript, Python, PHP, Ruby, Go, Rust, Java, .NET, Swift, Kotlin, Dart, and Elixir, framework integrations from Laravel to Next.js, and tooling for the CLI, CI, Terraform, and the automation platforms.
- SDKs Overview
Every official FoPost client, what it covers, and how to pick one.
- TypeScript SDK
The official TypeScript and Node.js client for the FoPost API.
- PHP SDK
The official PHP client for the FoPost API, with no framework and no HTTP library.
- Ruby SDK
The official Ruby client for the FoPost API, with no runtime dependencies.
- Go SDK
The official Go client for the FoPost API.
- Rust SDK
The official Rust client for the FoPost API, async and built on reqwest.
- Java SDK
The official Java client for the FoPost API, on the JDK's own HTTP client.