onepostly 0.2.21

Official Python SDK for the Onepostly API — publish, schedule, and read results
across all supported social platforms with one request shape. See the docs for the current platform list.

Python 3.10+.

Installation

pip install onepostly

Usage

Every resource is its own API class built on a shared Configuration and ApiClient. Create an API key in the dashboard; it is sent as Authorization: Bearer op_….

import asyncio
import os

from onepostly import ApiClient, Configuration
from onepostly.api.accounts_api import AccountsApi
from onepostly.api.posts_api import PostsApi


async def main() -> None:
    configuration = Configuration(access_token=os.environ["ONEPOSTLY_API_KEY"])
    async with ApiClient(configuration) as api_client:
        accounts = await AccountsApi(api_client).list_accounts()

        created = await PostsApi(api_client).create_post(
            create_post_body={
                "text": "Hello from Onepostly.",
                "accounts": [{"accountId": accounts.data[0].id}],
            },
        )
        # One post per account, all sharing created.group_id.
        for post in created.data:
            print(post.id, post.platform, post.status)  # "publishing"


asyncio.run(main())

Methods are async and return deserialized pydantic models. The …with_http_info() variants return an ApiResponse with status_code, headers, and raw_data alongside data.

Pass plain dicts anywhere a model is expected. Pydantic validates them, and the API's field names (accountId, scheduledFor) work as keys.

The examples below run inside the same async with ApiClient(configuration) as api_client: block.

Scheduling

posts = PostsApi(api_client)

await posts.create_post(
    create_post_body={
        "text": "Join our product webinar next week.",
        "scheduledFor": "2027-03-15T09:00:00",  # local time in `timezone`
        "timezone": "America/New_York",
        "accounts": [{"accountId": "acc_…"}],
    },
)
# 201 Created, status "scheduled"

await posts.update_post("pst_…", update_post_body={"scheduledFor": "2027-03-16T09:00:00"})
await posts.delete_post("pst_…")  # cancels a scheduled post

Media

Create a media item, upload the file to its upload_url, then use its id in a post:

import httpx

from onepostly.api.media_api import MediaApi

with open("launch.mp4", "rb") as f:
    content = f.read()

item = await MediaApi(api_client).create_media(
    create_media_body={"filename": "launch.mp4", "contentType": "video/mp4", "size": len(content)},
)

httpx.put(item.upload_url, content=content, headers={"Content-Type": "video/mp4"})

await posts.create_post(
    create_post_body={
        "text": "Launch day",
        "media": [{"id": item.id}],
        "accounts": [{"accountId": "acc_…"}],
    },
)

The upload URL needs no API key and accepts exactly the declared type and size.

Analytics

from onepostly.api.analytics_api import AnalyticsApi

analytics = AnalyticsApi(api_client)

result = await analytics.get_post_analytics("pst_…")
print(result.status, result.metrics)

timeline = await analytics.get_post_analytics_timeline(
    "pst_…",
    since="2027-03-01T00:00:00Z",
    until="2027-03-29T00:00:00Z",  # exclusive
)

Error handling

Every non-2xx response raises an ApiException subclass with the HTTP status, reason, and the raw response body attached. Subclasses map to status families (UnauthorizedException, ForbiddenException, NotFoundException, ConflictException, ServiceException, …). The body has a stable code to build logic on, and a requestId to share with support:

from onepostly import ApiException

try:
    await posts.create_post(create_post_body={...})
except ApiException as error:
    print(error.status, error.body)
    # 400 {"error": "Invalid request: …", "code": "VALIDATION_ERROR", "param": "accounts.0.accountId", "requestId": "req_…"}

See Errors for every code.

API reference

Methods take their parameters by name; path parameters can also go first, in path order.

AccountsApi

ConnectApi

ProfilesApi

MediaApi

PostsApi

AnalyticsApi

CommentsApi

EngagementApi

InboxApi

AutomationsApi

WebhooksApi

WalletApi

A JSON body goes in under its schema name, such as create_post_body. Every operation, with request and response examples in Python, is in the API Reference.

Links

• Documentation
• API Reference
• Dashboard
• OpenAPI spec

License

Apache-2.0