Postemi developer resources: API, MCP, OpenAPI, CLI

At a glance

Postemi developer documentation in English: REST API, MCP server, OpenAPI, CLI

Postemi is a social media scheduler. It publishes and schedules posts to 12 social platforms, and it can be driven entirely by a machine through a public REST API, an MCP server or a command line tool. This section is the same reference as the rest of the page, in English, for developers and agents arriving from an English search. The product interface is available in Hungarian, English, German and Czech.

Getting started is self-serve

• Sign-up: self-serve at https://postemi.com/app/signup. Registration is free and involves no sales call, no demo request, no waiting list and no manual approval.
• API keys: self-serve. You create them yourself after signing up, inside the app under Automations → Developers: an API key for the REST API and the CLI, an MCP key for chat clients. Nobody has to issue one for you, and no sales contact is involved. A key is shown once, at creation.
• Free tier: there is no permanently free publishing plan. Up to 5 channels can be connected before subscribing, so a new account can see its own channels, but nothing is published or scheduled without a plan. Every plan starts with a 7 day free trial. A card is collected when the trial starts, because checkout is a Stripe subscription session, and nothing is charged during the trial.
• Support: [email protected].

Public REST API

The REST API answers at https://api.posty.hu. Public routes sit under the /public/v1 prefix. It manages the same workspace as the web interface, just from your code.

Authentication

Every request carries an API key in the Authorization header. You create the key in Postemi, on the Automations → Developers page. You do not need to write to us for that. The key is shown once, at the moment you create it, and cannot be retrieved later, so save it immediately. Keys can be scoped: their permissions move with the owner's current role, and a key belonging to a user who leaves the workspace stops working.

If a key belongs to more than one workspace, the showorg header selects which one the call applies to.

What v1 can do

• List connected social accounts: GET https://api.posty.hu/public/v1/integrations
• Create and schedule a post: POST https://api.posty.hu/public/v1/posts
• Query the calendar, update, delete: GET https://api.posty.hu/public/v1/posts, DELETE https://api.posty.hu/public/v1/posts/:id
• Upload media from a file or a URL: POST https://api.posty.hu/public/v1/upload, POST https://api.posty.hu/public/v1/upload-from-url
• A browser upload link, when the file is on the user's device: POST https://api.posty.hu/public/v1/upload-link, GET https://api.posty.hu/public/v1/upload-link/:id
• Find the next free slot: GET https://api.posty.hu/public/v1/find-slot/:id
• Analytics for a channel and a post: GET https://api.posty.hu/public/v1/analytics/:integration

Status and discovery without authentication

GET https://api.posty.hu/public/v1/status is the only route that answers without a key. It returns the API version, the exact server time in UTC, and absolute URLs for every machine-readable document: the OpenAPI description, the OAuth metadata, the MCP endpoint. It does not return workspace data, and it accepts no parameters. An agent can use it to decide, in one call, whether we are reachable and where to look next.

Errors

Every error returns JSON. In errors raised by Postemi, the msg field carries the human sentence. Calls that fail request validation get the framework shape (statusCode, message, error). A permissions 403 names the missing scope and the key owner's current role, because the most common cause is not a badly created key, but a demoted user. The OpenAPI document's ApiError schema describes all of this in a machine-readable way, per status code, including whether it is worth retrying.

Rate limits

Every response carries the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (in seconds) and RateLimit-Policy headers, with a separate budget per route. A 429 also comes with Retry-After. Do not wait for the 429: you can slow down in advance 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 would keep its contract. Additions (a new optional field, a new route, a new enum value) happen inside v1, so your client code should ignore fields it does not know.

If we deprecated a route, its response would get a Deprecation: true header, a Sunset header with the date after which it no longer works, and a Link header with the details. The Sunset date is never closer than 180 days from the first Deprecation header. Nothing is currently deprecated.

MCP server

The MCP server address is https://api.posty.hu/mcp, with streamable HTTP transport. Through it, your agent sees the same channels and schedules into the same calendar as you.

• Key for clients: an MCP key starting with psty_mcp_…, from the Automations → Developers page. The MCP server deliberately refuses REST keys that start with psty_…, and it says why.
• Key for apps: an OAuth access token starting with pos_…. It expires, can be refreshed, and is only valid for the address it was issued for.
• You copy a ready-made setup block for Claude, ChatGPT, Muse, Hermes and OpenClaw from the Automations → Developers page. The write-up is on the AI agents page.

Command line tool

The posty-cli package is published on npm. Install: npm install -g posty-cli, and the command is posty. Sign in with browser approval: posty auth:login.

The package includes SKILL.md, which describes every command and flag. An agent with a shell learns how to use it from that file, without reading a web page. The CLI writes the JSON response to stdout, status and errors to stderr, and on a failed run it exits non-zero, so the calling program knows what happened.

Subscribing through an agent

An agent (Claude, the CLI or a REST client) can take a person from "subscribe me to Pro yearly" to a live subscription. One step stays human: authorising the payment on Stripe's Checkout page, where Link is the merchant of record. The agent quotes the plans, asks for a link, and after the payment confirms that the plan is live.

• It works without an account: from the OAuth consent screen, signing in or registering (e-mail or Google) brings the person back to the same consent request. There is no MCP tool for registration; over REST and in the CLI an agent can create the account too, see below.
• MCP: get_plans (the four plans, prices and limits), subscribe (a Stripe Checkout link for the chosen plan), get_subscription (the state; the agent confirms with it after the payment), manage_subscription (the Stripe billing portal: plan change, cancellation, invoices, card). These are the only tools that may name a plan, and they are called only when the user asks.
• REST: GET /plans, GET /subscription, POST /subscriptions/checkout, GET /subscription/portal. CLI: posty billing:plans, posty billing:subscribe --tier pro --period yearly, posty billing:status, posty billing:manage.
• The payment happens in Stripe Checkout, with the person's own Link wallet or card. An agent must never pay with a one-time or agent-issued card: a Postemi subscription renews monthly or yearly, and a one-time card fails at the first renewal, which ends the plan.
• A workspace whose plan has no API access yet is served only these four tools on an MCP connection; after the payment the rest appear on the next tool list. subscribe and manage_subscription work on connections made by signing in (OAuth), for the workspace payer; on REST they need an OAuth token or a full-workspace psty_sa_ key. On the ChatGPT surface none of the four subscription tools is available; there, people subscribe on postemi.com.

Creating an account through an agent

An agent (the CLI, a script or an assistant with a REST tool) can create a Postemi account for a person without a browser. The account is real, activated and belongs to the person; the agent receives a full workspace key for it.

• A code by e-mail: POST /signup/start sends a one-time code to the person's address. The person reads the code to the agent, and the agent completes the sign-up with POST /signup/complete. The code is valid for 10 minutes.
• The person must agree to the terms: the agent shows them the terms and the privacy notice, and sends acceptTerms: true only after they agree. The consent is recorded the same way as for a web registration.
• An account created this way has no free trial. The next step is the checkout: GET /plans, then POST /subscriptions/checkout, and the person pays on Stripe's page. The API and MCP open only on a plan that includes them: apiAndMcpAccess: true in the answer of GET /plans. Basic does not include them, so when the person picks Basic, the agent tells them first that the key will not reach the API after the payment either. The person connects their channels in the web app.
• If the address already has an account, no new one is made: the person signs in with posty auth:login or over OAuth. A person who registers in the browser keeps the trial.
• CLI: posty auth:signup --email [email protected], then posty billing:plans and posty billing:subscribe --tier pro --period yearly.

Webhooks

You set webhooks up in Postemi, and every delivery is signed. The signature arrives in the X-Posty-Signature header, in the shape t=<unix seconds>,v1=<hex hmac-sha256>. That is deliberately the same shape as Stripe's signature, so existing verification libraries work with it.

• The signature is computed over the raw request body. If your framework first parses it as JSON and re-serializes it, you get a different string, and verification fails.
• The timestamp is part of the signature. That is the replay protection. The tolerance is 300 seconds.
• You get the signing secret when you create the webhook, and you can regenerate it in Postemi at any time.

OAuth apps

If you are not managing your own account, but other people's from an app, you use OAuth. Authorization goes through the authorization code flow, and the following are required.

• A PKCE S256 challenge on every request. A client without a secret can be registered, but not without PKCE.
• redirect_uri must match the registered list exactly.
• Tokens expire, and we rotate the refresh token. We only store their hashed form.
• The token is good for the scopes the user consented to, and on every call we intersect that with the user's current role. A demotion takes effect on the next call.
• An app can be authorized by a workspace member with the SUPERADMIN role.

Access and getting started

The whole flow is self-serve. You do not need to talk to sales, and you do not need to request a demo.

• You register on the /app/signup page. Registration is free.
• You connect your social accounts with the usual OAuth flow.
• You create a key on the Automations → Developers page: an API key for the REST API and the CLI, an MCP key for the chat client.
• Every plan starts with a 7-day free trial. We ask for a card to start the trial, but we charge nothing during it. Nothing is due today, and you can cancel anytime before it ends. Prices are on the pricing section.

Machine-readable

If you are writing an agent, do not parse HTML. Start from these documents.

If you get stuck

Write to [email protected], or use the form on the Help page. On weekdays we usually reply within a day.