Log in Start free
Log in Start free

REST v1

A key, a bearer token, and the same API the app uses.

Postey's own client talks to this surface and nothing else. API keys are a paid-plan feature. The free plan cannot mint one, and this page says so before you write any code.

Start free Read the docs
terminal 
curl https://srvr.postey.ai/v1/posts \
  -H "Authorization: Bearer $POSTEY_API_KEY" \
  -G --data-urlencode "account_id=1"
One bearer header. The v1 tree mounts 70 routers behind it.

Keys are scoped before they are issued

A key is not simply "your account". You choose how far it reaches and what it may do, at the moment you mint it, and you can narrow it afterwards. Key management itself refuses any request that is authenticated by a key, so a leaked key cannot mint a replacement for itself.

Reach

  • FULL_ACCESS Everything the owning user can reach.
  • TEAM_SPECIFIC One team, and nothing outside it.
  • ACCOUNT_SPECIFIC One social set, and nothing outside it.

Permissions

Granted per resource, not once for the whole key.

  • READ
  • EDIT
  • DELETE

Resources

The five areas a permission can be granted over.

  • POST
  • PUBLISHING
  • SCHEDULING
  • ANALYTICS
  • COMMENTS

The endpoints, by family

67 endpoints across 10 families, each one read off the router that declares it. The v1 tree mounts 70 routers in total, so this is the part you integrate against rather than the whole of it.

Posts 9

app/routers/v1/posts/posts.py

  • GET /v1/posts List posts for an account.
  • POST /v1/posts Create a draft.
  • GET /v1/posts/search Search across posts.
  • GET /v1/posts/trash List trashed posts.
  • GET /v1/posts/{post_id} Read one post.
  • PATCH /v1/posts/{post_id} Update one post.
  • POST /v1/posts/{post_id}/convert Reshape a post for other platforms. Mechanical, not a model call.
  • POST /v1/posts/{post_id}/restore Restore from trash.
  • DELETE /v1/posts Trash or delete posts.
Publishing 3

app/routers/v1/publish/publish.py

  • POST /v1/publish Publish a draft now.
  • GET /v1/publish/{post_id}/status Per-platform publish state for one post.
  • DELETE /v1/publish/cancel Cancel an in-flight publish.
Scheduling 7

app/routers/v1/schedules/schedules.py · schedules/calendar.py

Scheduling is a paid entitlement, so `scheduling` is false on Free.

  • GET /v1/schedules List schedules.
  • POST /v1/schedules Schedule a draft.
  • PATCH /v1/schedules Move a schedule.
  • DELETE /v1/schedules Unschedule.
  • GET /v1/schedules/post/{post_id} The schedule attached to one post.
  • GET /v1/schedules/calendar The calendar view, including any automatic hold on a slot.
  • GET /v1/schedules/calendar/slots Free slots against your posting preferences.
Accounts 7

app/routers/v1/accounts/accounts.py

  • GET /v1/accounts List social sets.
  • POST /v1/accounts Create a social set.
  • GET /v1/accounts/{account_id} Read one social set.
  • PATCH /v1/accounts/{account_id} Rename or edit it.
  • DELETE /v1/accounts/{account_id} Delete it.
  • DELETE /v1/accounts/{account_id}/socials Disconnect a network from it.
  • POST /v1/accounts/reconnect-request Ask a teammate to re-authorise a stale credential.
Media 8

app/routers/v1/media/media.py, with chunked/, drive/ and url/ nested under it

  • POST /v1/media Upload media against a post.
  • POST /v1/media/unlinked Upload before a post exists.
  • DELETE /v1/media/{media_id} Delete an upload.
  • POST /v1/media/chunked/init Open a chunked upload for a large video.
  • PATCH /v1/media/chunked/{upload_id} Send one chunk.
  • POST /v1/media/chunked/{upload_id}/complete Finalise the upload.
  • GET /v1/media/chunked/{upload_id}/status Poll a chunked upload.
  • POST /v1/media/url/import Stream media in from a URL.
Analytics 7

app/routers/v1/analytics/account_analytics.py · analytics/post_analytics.py

Analytics is a paid entitlement, and collection covers seven of the nine networks.

  • GET /v1/analytics/overview Headline numbers for a set.
  • GET /v1/analytics/followers Follower series.
  • GET /v1/analytics/engagements Engagement series.
  • GET /v1/analytics/impressions Impression series.
  • GET /v1/analytics/streak Posting streak.
  • GET /v1/analytics/posts Per-post figures.
  • GET /v1/analytics/account/{account_id} One account, broken out.
Published posts 7

app/routers/v1/published_posts/published_posts.py

  • GET /v1/published-posts What actually went out.
  • GET /v1/published-posts/{post_id} One published post.
  • GET /v1/published-posts/cross-platform/{post_id} The same idea across every network it landed on.
  • GET /v1/published-posts/platform-comparison Network against network.
  • GET /v1/published-posts/threads Published threads.
  • GET /v1/published-posts/engagement-scores Scored engagement per post.
  • DELETE /v1/published-posts/{post_id}/{account_id} Remove a published post from Postey’s record.
Comments 6

app/routers/v1/posts/comments.py

These are Postey’s own review notes on a draft. They are never published to a network.

  • GET /v1/comments/{doc_id}/{account_id} Read the notes on a draft.
  • POST /v1/comments/{doc_id}/{account_id} Leave a note.
  • POST /v1/comments/{doc_id}/{comment_id}/{account_id}/reply Reply in a thread.
  • POST /v1/comments/{doc_id}/{account_id}/guest A note from someone with a share link and no seat.
  • PATCH /v1/comments/{doc_id}/{comment_id}/{account_id}/resolve Resolve a thread.
  • GET /v1/comments/{doc_id}/{account_id}/stats Open and resolved counts.
Tags and teams 7

app/routers/v1/tags/tags.py · app/routers/v1/teams/team.py

  • GET /v1/tags List tags.
  • POST /v1/tags Create a tag.
  • PATCH /v1/tags/{tag_id} Rename a tag.
  • DELETE /v1/tags/{tag_id} Delete a tag.
  • GET /v1/teams List teams.
  • GET /v1/teams/{team_id} Read one team.
  • GET /v1/teams/{team_id}/contributors Who has touched what.
Keys and grants 6

app/routers/v1/api/keys.py · app/routers/v1/api/oauth_grants.py

Key management refuses a request that is itself authenticated by an API key.

  • GET /v1/keys List your keys.
  • POST /v1/keys Mint a key.
  • PATCH /v1/keys/{key_id} Rescope a key.
  • DELETE /v1/keys/{key_id} Revoke a key.
  • GET /v1/oauth-grants Every agent that has been granted access.
  • DELETE /v1/oauth-grants/{grant_id} Revoke one agent’s access.

Three things the shape will tell you

Publishing and analytics are different sets

The publish and schedule endpoints reach nine networks. Analytics collection covers seven of them. They are separate numbers because they are separate systems, and an analytics response for a network with no collector will tell you that rather than returning an empty series you might mistake for a quiet week.

A post can be held without anyone reviewing it

There is no review state in the post model. What the calendar endpoint can return is an automatic hold, a scheduled slot stopped by billing standing or by a network's own rate ceiling, and released again automatically when the cause clears. Build for a hold you did not ask for, not for a queue someone has to clear.

Reshaping content is not a model call

POST /v1/posts/{post_id}/convert adapts a post across networks deterministically. The same input gives the same output, and it costs nothing against an AI allowance, because there is no model in the path. Postey's rewrite feature is a separate, model-backed, paid thing.

What a key costs

The API is a paid-plan feature and the catalog is explicit about it. The one developer surface that is not gated is MCP, which is why it has its own page.

  • Mint a REST API key api_keys is false on Free, so every key type except MCP is gated Paid plan
  • Hold more than five keys of one type The cap is per key type, and MCP keys do not count against it Paid plan
  • Read and write drafts, publish them Reachable once you hold a key; the underlying plan limits still apply Paid plan
  • Schedule through the API scheduling is false on Free, independently of the key Paid plan
  • Read the analytics endpoints analytics is false on Free, independently of the key Paid plan
  • Connect an agent over MCP instead An MCP key is outside can_use_api_keys. See the MCP page Free

Read from the live plan catalog at srvr.postey.ai/v1/payment/plans and app/routers/v1/api/keys.py, 18 August 2026.