API Basics
Data Formats
Id prefixes, timestamp format, open enums and null fields across the Onepostly API.
These rules hold for every endpoint and every webhook. Build your client on them, and it keeps working as the API grows.
Id Prefixes
Every id starts with a prefix that names its kind.
| Prefix | Points to | Example |
|---|---|---|
acc_ | Account | acc_1699f4157fb643f49d2ac447491f32a8 |
pst_ | Post | pst_3c8a2d6e91b44f7a8e250d6b4c1f9a73 |
grp_ | Posts of one create request | grp_7d2e5b1a9c4f4a68b3e07f1c2d9a6e45 |
med_ | Media | med_7f3a9c2e1b4d4e8f9a6b5c4d3e2f1a0b |
whk_ | Webhook endpoint | whk_e5c7a3f18b2d4e69a04c3f9d1b7e2c58 |
dlv_ | Webhook delivery | dlv_9f3e6b2a4c1d4a8eb7f51d2c8e0a6b49 |
aut_ | Automation | aut_4b8e2f6a1c9d4e37a5b02c8f6d1e9a33 |
cmt_ | Comment | Varies in length |
cnv_ | Conversation | Varies in length |
evt_ | Webhook event | evt_7c41e09a5b3d4f2e8a6c1b9d0e3f5a72 |
req_ | API request | req_8f2a64c1d3b94e0f9a7c5e2b1d0f3a6c |
An id with the wrong prefix fails fast.
| Where you send it | Response |
|---|---|
| In the path | 404 NOT_FOUND, or ACCOUNT_NOT_FOUND on account paths |
| In the body or query | 400 VALIDATION_ERROR with the field in param |
Opaque Ids
Treat ids as opaque strings. Do not parse them, build them or rely on their length. A 512-character string column fits every kind.
cmt_ and cnv_ ids belong to your workspace. They stay the same there, so you can store them. Another workspace gets other ids, and yours return 404 NOT_FOUND there. Get them from List Comments and the Inbox.
An evt_ id names one webhook event. Every retry of that event carries the same id, so use it to skip handled events. See Webhooks.
Platform Ids
Fields named platform..., such as platformPostId, hold the platform's own id. The platform sets its format, such as a number on X or an at:// URI on Bluesky. Some fields take both kinds. quotePostId takes a pst_ id or a platform post id. See Post References.
The platform field holds one of these.
platform | Platform |
|---|---|
x | X (Twitter) |
instagram | |
facebook | |
threads | Threads |
linkedin | |
youtube | YouTube |
tiktok | TikTok |
pinterest | |
bluesky | Bluesky |
Timestamps
Response timestamps are ISO 8601 in UTC with milliseconds, such as 2027-03-15T13:00:00.000Z. These fields differ.
| Field | Format | Example |
|---|---|---|
scheduledFor | Local time in timezone, no zone. See Scheduling | 2027-03-15T09:00:00 |
timezone | IANA time zone | America/New_York |
Timeline day | UTC date | 2026-08-01 |
X-RateLimit-Reset | Unix seconds | 1789473600 |
Retry-After | Seconds to wait | 12 |
In requests, since and until need Z or an offset. See Time Filters.
Open Enums
Response fields can gain new values. Handle a value you do not know.
| Field | Known values |
|---|---|
Post status | Post Status |
platform | Platform Ids |
mediaKind | Media Kinds |
Error code | Error Codes |
Account status | Account Status |
Media status | Media |
Analytics status | Analytics Status |
Delivery status | Delivery Log |
- An unknown post
statusis not final. Read the post again later. - An unknown account
statusmay need attention, like any status butactive. - Handle an unknown error
codeby its HTTP status. - The SDKs accept any string here, so they read values added later.
Responses can gain fields, so ignore ones you do not know. Requests are strict, and an unknown field or value returns 400 VALIDATION_ERROR.
Null Fields
A field without a value is null, not left out. A few platform-only fields, such as xSubscriptionType, are left out on other platforms.
| Field | null means |
|---|---|
platformPostId, url, publishedAt | Not published yet |
scheduledFor, timezone | Not scheduled |
error | Did not fail |
metrics | No metrics yet |
One metric, such as metrics.saves | Not reported for this post |
groupId, text | Made outside Onepostly |
nextCursor | Last page |
Lists are never null. No media is media: [], and no options is options: {}. These are left out instead of null.
- Error envelope fields that do not apply, such as
param. - Include extras you did not ask for, such as
total.