Postemi API, MCP and CLI reference

A separate page per endpoint, with parameters and runnable examples, lives in the full documentation: postemi.com/docs/api/endpoints.

How it works

Postemi handles the same workspace as the web app, on three surfaces. The REST API from your own code, the command-line tool from the terminal and your scripts, and the MCP server from an AI agent. All three use the same permissions and limits, so what you can do on one, you can do on the others.

The REST API base URL is https://api.posty.hu/public/v1. The version is in the path, and every response is JSON.

Connecting in three steps

1. Sign up at postemi.com/app/signup. No sales call, no waiting list.
2. Connect at least one social account in the app. You cannot do this step from the API, because the platform asks a person for consent.
3. Create a key for yourself: Automations → Developers. The key is shown once, at the moment you create it.

Your first call can check that everything is in place. This endpoint responds even without a key, and tells you where to find everything:

curl https://api.posty.hu/public/v1/status

And your first authenticated call lists your channels:

curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: psty_a_your_key"

Authentication

Two kinds of credentials work. The API key is the entire Authorization header value (psty_…), and it is for your own code. The OAuth 2.1 access token (Bearer pos_…) is what you need when another application accesses Postemi on behalf of your users. The flow uses PKCE, and the metadata is machine-readable.

A key's permissions follow its owner's current role. If someone is demoted or removed from the workspace, their key immediately has only as much access as they do. If a key belongs to more than one workspace, the showorg header chooses among them.

Endpoints

Every path is under https://api.posty.hu/public/v1. The Scope column shows which scope the key needs. If it is missing, the response is 403, and it names the missing one.

The exact request and response schemas, field by field, are in the OpenAPI 3 description. You can generate client code from it too.

Example: a scheduled post

The date is always UTC, in ISO 8601 format. type can be draft, schedule or now.

curl -X POST https://api.posty.hu/public/v1/posts \
  -H "Authorization: psty_a_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2026-09-15T09:00:00.000Z",
    "shortLink": false,
    "posts": [{
      "integration": { "id": "your_channel_id" },
      "value": [{ "content": "<p>Hello everyone!</p>" }]
    }]
  }'

The response returns one row per channel, with the postId you use for deletion and status changes.

Errors

Every error is JSON. In errors raised by Postemi, the msg field carries the human sentence. Calls that fail request validation get the framework's shape (statusCode, message, error). A permission 403 names the missing scope and the key owner's role, because the most common cause is not a bad key, but a demoted user.

The status code tells you whether it is worth retrying: 400, 401, 403 and 404 will not go away until you change something. 429 and 5xx will. The ApiError schema also describes all of this in a machine-readable way in the OpenAPI document.

Rate limits

Every response carries the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (in seconds, not a timestamp) and RateLimit-Policy headers. 429 also comes with Retry-After. Every path has its own window, per key. Do not wait for the 429: you can slow down ahead of time from the remaining value.

Versioning and deprecation

The version is in the path: every public call lives under /public/v1. A breaking change would appear as a new version (/public/v2), and v1 keeps its contract. Additions happen inside v1: a new optional field, a new path, a new enumerated value. Your code should ignore fields it does not know.

If we were to deprecate a path, its response would get a Deprecation: true header, plus a Sunset header with the date after which it no longer works. That date is never less than 180 days away. Every response also carries a Link header with a rel="sunset" relation, pointing at this section. Nothing is currently being deprecated.

Command-line tool

posty-cli uses the same API, just from the terminal. Install and sign in:

npm install -g posty-cli
posty auth:login
posty integrations:list

Sign-in opens a browser and stores the key on your machine, so you do not have to put it in your scripts. Every command can emit --json output, which is for machine processing.

MCP server

The MCP server address is https://api.posty.hu/mcp-oauth, with streamable HTTP transport and OAuth 2.1 authentication. Your agent sees these tools:

The connection asks for authentication: without credentials the server returns 401, and the WWW-Authenticate header tells you where to request permission. This is not an error, it is the start of the flow according to the MCP standard. The tool list can still be read from the manifest.

Machine-readable

Every document an agent or a generator asks for:

• OpenAPI 3: https://posty.hu/openapi.json
• MCP manifest: https://posty.hu/.well-known/mcp.json
• Status and discovery: https://api.posty.hu/public/v1/status
• OAuth metadata: https://api.posty.hu/.well-known/oauth-protected-resource
• Short summary for agents: https://postemi.com/llms.txt