Python SDK method reference
Every public method of the socifyr package, version 0.1.0. All methods return the data part of the API response as a plain dict or list. Keyword-only arguments are shown after *.
from socifyr import Socifyr
client = Socifyr(api_key="sk_...", workspace_id="ws_...")Client
| Member | Signature | Notes |
|---|---|---|
| constructor | Socifyr(api_key=None, workspace_id=None, *, base_url=None, timeout=30.0) | Raises ValueError without an API key. See configuration |
usage | usage() -> dict | Shortcut for workspaces.usage() |
| attributes | uploads, workspaces, analytics, ai |
How do I call the uploads methods?
| Method | Signature | Calls |
|---|---|---|
text | text(*, connections: list[str], text: str, scheduled_at: str | None = None, timezone: str | None = None, first_comment: str | dict | None = None, save_draft: bool | None = None) -> dict | POST /content/text |
photos | photos(*, connections: list[str], medias: list[str], text: str | None = None, scheduled_at: str | None = None) -> dict | POST /content/photos |
video | video(*, connections: list[str], medias: list[str], text: str | None = None, scheduled_at: str | None = None) -> dict | POST /content/video |
bulk_schedule | bulk_schedule(*, rows: list[dict] | None = None, csv: str | None = None) -> dict | POST /content/bulk-schedule |
get_status | get_status(request_id: str) -> dict | GET /content/status?requestId= |
list | list(**query) -> dict | GET /content |
get | get(upload_id: str) -> dict | GET /content/:id |
retry | retry(upload_id: str) -> dict | POST /content/:id/retry |
publish_draft | publish_draft(upload_id: str) -> dict | POST /content/:id/publish |
Behavior shared by text, photos and video: arguments set to None are omitted from the request, and the SDK always adds "async": true. medias entries are media library IDs or public URLs. Snake-case arguments are converted to the API's camelCase (scheduled_at becomes scheduledAt).
Ack example (non-draft):
{"success": True, "requestId": "9f2c7a1e-...", "usage": {"count": 4, "limit": 100, "remaining": 96},
"message": "Upload processing started", "scheduledAt": None, "totalChannels": 2}bulk_schedule returns {"created": int, "failed": [{"row": int, "error": str}]}. Row dicts use the API keys: text, connections, scheduledAt, optional title.
list(**query) forwards its keyword arguments as query parameters. Known keys: page, limit, status, platform, type, from, to. Use list(**{"from": "2026-11-01"}) for from. The response is {"data": [...], "meta": {"total", "page", "limit", "totalPages"}}.
Runnable example:
ack = client.uploads.text(connections=["x-myhandle"], text="Hello")
status = client.uploads.get_status(ack["requestId"])
print(status["status"], status["uploadId"])Details: Uploads.
How do I call the workspaces methods?
| Method | Signature | Calls |
|---|---|---|
list_connections | list_connections(workspace_id: str) -> list[dict] | GET /workspaces/:id/connections |
refresh_connection | refresh_connection(workspace_id: str, connection: str) -> dict | POST /workspaces/:id/connections/:connection/refresh |
reconnect_link | reconnect_link(connection: str) -> dict | POST /oauth/connections/:connection/reconnect-link |
usage | usage() -> dict | GET /usage |
refresh_connection returns id, slug, platform, expiresAt, lastRefreshedAt, status, canRefresh. reconnect_link returns url, expiresIn (seconds), platform, slug. Path values are inserted without URL encoding, so pass slugs and IDs as-is. Details: Workspaces.
How do I call the analytics methods?
| Method | Signature | Calls |
|---|---|---|
get | get(**query) -> dict | GET /analytics |
get_post | get_post(upload_id: str) -> dict | GET /analytics/post/:id |
sync | sync() -> dict | POST /analytics/sync |
followers | followers(*, period=None, from_date=None, to_date=None, connection=None, platform=None) -> dict | GET /analytics/followers |
accounts | accounts(*, period=None, from_date=None, to_date=None, connection=None, platform=None) -> dict | GET /analytics/accounts |
from_date and to_date are sent as from and to. Details: Analytics.
How do I call the AI methods?
| Method | Signature | Calls |
|---|---|---|
generate_caption | generate_caption(*, upload_type: str, platforms: list[str], text: str | None = None, title: str | None = None, description: str | None = None, tone: str | None = None) -> dict | POST /ai/generate-content |
suggest_hashtags | suggest_hashtags(*, text: str, platforms: list[str], count: int | None = None) -> dict | POST /ai/suggest-hashtags |
upload_type is video, photo, text or document. platforms are platform names such as instagram, not slugs. tone is professional, casual, humorous, inspirational or informative. Requires an AI key on the workspace, otherwise the API returns 503.
res = client.ai.generate_caption(upload_type="text", platforms=["x", "linkedin"], text="We shipped v2", tone="casual")
print(res["content"]["x"]) # {"content": {platform: caption}}
tags = client.ai.suggest_hashtags(text="Launching our SDK", platforms=["instagram"], count=10)
# [{"platform": "instagram", "hashtags": [...]}]The return annotation says dict, but the API returns a list for hashtags, as in the TypeScript SDK. Treat the value as a list of {platform, hashtags}.
How do I verify a webhook?
| Function | Signature |
|---|---|
verify_webhook_signature | verify_webhook_signature(payload: str | bytes, signature: str, secret: str) -> bool |
See Webhooks.
Exceptions
SocifyrError(message, status=None), ValidationError (400), AuthenticationError (401, 403), UsageLimitError (402), NotFoundError (404), RateLimitError (429). See Errors.
FAQ
Are the return values typed?
No. They are dict and list. Use the TypeScript SDK types or the REST API reference for field lists.
Is there a method for X?
If it is not in the tables above, it does not exist in the Python SDK. See the parity table.