---
title: "Posty API and CLI reference: REST, MCP, OpenAPI | API documentation"
description: "Posty API documentation: every public REST endpoint with curl examples, the posty-cli command reference, the MCP tool list, authentication, error model, rate limits and the versioning policy. The complete reference for Posty's public API and command-line tool."
canonical: https://posty.hu/en/api
source: https://posty.hu/en/api.md
---

API documentation

# Posty API, MCP and CLI reference

This page is the complete reference for Posty's programmable surfaces: every public REST endpoint, every command in the command-line tool, and the MCP server's tools. If you have not decided which surface you need, [the developer overview](https://posty.hu/en/developers) is where to start.

A separate page per endpoint, with parameters and runnable examples, lives in the full documentation: [posty.hu/dokumentacio/api/vegpontok](https://posty.hu/en/docs/api/endpoints).

## How it works

Posty 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 [posty.hu/regisztracio](https://posty.hu/regisztracio). 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: Settings → 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_kulcsod"
```

### 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 Posty 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.

| Method | Path | What it does | Scope |
| --- | --- | --- | --- |
| GET | /status | Állapot és felderítés. Az egyetlen útvonal, amely kulcs nélkül is válaszol. | — |
| GET | /is-connected | Ellenőrzi, hogy a kulcs érvényes munkaterületre mutat-e. | — |
| GET | /integrations | A bekötött csatornák: azonosító, név, @handle, platform, és hogy tud-e most posztolni. | channels:read |
| GET | /integration-settings/:id | Egy csatorna posztolási szabályai és beállítássémája, a fiókra feloldott karakterkorláttal. | channels:read |
| POST | /integration-trigger/:id | Platformspecifikus lekérdezés egy csatornán: táblák, subredditek, oldalak listája. | channels:read |
| GET | /social/:integration | Visszaadja azt a platformcímet, amit egy embernek meg kell nyitnia a csatorna bekötéséhez. | channels:write |
| GET | /groups | Az ügyfélcsoportok, amelyekbe a csatornák be vannak sorolva. | channels:read |
| GET | /posts | A naptár egy időszakra: minden poszt állapottal és időponttal. | posts:read |
| POST | /posts | Poszt létrehozása: piszkozat, ütemezés vagy azonnali közzététel, egy vagy több csatornára. | posts:draft (közzétételhez posts:publish is) |
| DELETE | /posts/:id | Egy poszt törlése és a hozzá tartozó folyamat leállítása. | posts:draft |
| DELETE | /posts/group/:group | A teljes csoport törlése: egy szerkesztés, ami több csatornára ment ki, egyetlen posztnak számít. | posts:draft |
| PUT | /posts/:id/status | Poszt átmozgatása piszkozat és ütemezett állapot között. | posts:publish |
| GET | /posts/:id/missing | Megmondja, mi hiányzik még a poszthoz a közzétételhez. | posts:read |
| PUT | /posts/:id/release-id | A platformon kívül közzétett poszt azonosítójának és címének rögzítése. | posts:publish |
| GET | /find-slot/:id | A következő szabad időpont a munkaterület ütemezése szerint. | posts:read |
| POST | /upload | Kép vagy videó feltöltése a médiatárba, legfeljebb 1 GB. | media:write |
| POST | /upload-from-url | Médiafájl behúzása nyilvános URL-ről a médiatárba. | media:write |
| POST | /upload-link | Böngészős feltöltési link, ha a fájl a felhasználó eszközén van. | media:write |
| GET | /upload-link/:id | A feltöltési linken beérkezett fájlok, a posztba tehető címmel. | media:write |
| GET | /analytics/:integration | Egy csatorna statisztikái a kért időszakra. | analytics:read |
| GET | /analytics/post/:postId | Egy közzétett poszt platformstatisztikái. | analytics:read |
| GET | /notifications | A munkaterület értesítései, lapozva. | posts:read |

The exact request and response schemas, field by field, are in the [OpenAPI 3 description](https://posty.hu/openapi.json). 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_kulcsod" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2026-09-15T09:00:00.000Z",
    "shortLink": false,
    "posts": [{
      "integration": { "id": "a_csatorna_azonositoja" },
      "value": [{ "content": "<p>Sziasztok!</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 Posty, 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.

Hitelesítés

| posty auth:login | Böngészős bejelentkezés, a kulcsot a gép tárolja. |
| --- | --- |
| posty auth:status | Melyik munkaterülethez van kötve a gép. |
| posty auth:logout | A tárolt kulcs törlése. |

Csatornák

| posty integrations:list | A bekötött csatornák azonosítóval. |
| --- | --- |
| posty integrations:settings <id> | Egy csatorna szabályai és beállításai. |
| posty integrations:trigger <id> <method> | Platformspecifikus lekérdezés a csatornán. |

Posztolás

| posty posts:create -c "szöveg" --date "..." -i "<id>" | Ütemezett poszt egy vagy több csatornára. |
| --- | --- |
| posty posts:create -c "szöveg" -t draft ... | Ugyanaz piszkozatként, közzététel nélkül. |
| posty posts:create --json fajl.json | A teljes kérés fájlból, szkriptekhez. |

Kezelés

| posty posts:list | A naptár tartalma. |
| --- | --- |
| posty posts:delete <id> | Poszt törlése. |
| posty posts:status <id> --status draft | Váltás piszkozat és ütemezett között. |
| posty posts:find-slot <id> | A következő szabad időpont. |
| posty upload <fajl> | Médiafeltöltés a médiatárba. |
| posty upload:link | Böngészős feltöltési link, ha a fájl nem a gépen van. |
| posty upload:files <id> | Ami a feltöltési linken beérkezett. |

Analitika

| posty analytics:platform <id> -d 30 | Csatornastatisztika az elmúlt N napra. |
| --- | --- |
| posty analytics:post <id> | Egy poszt statisztikái. |
| posty posts:missing <id> | Mi hiányzik még a poszthoz. |

## 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:

| Tool | What it does | Writes? |
| --- | --- | --- |
| get\_workspace\_context | A pontos idő UTC-ben, a felhasználó időzónája és a munkaterület neve. | no |
| list\_integrations | A bekötött csatornák azonosítóval, @handle-lel és állapottal. | no |
| list\_groups | Az ügyfélcsoportok. | no |
| get\_integration\_schema | Egy csatorna szabályai és a fiókra feloldott karakterkorlát. | no |
| get\_channel\_options | Platformspecifikus választható értékek egy csatornához. | yes |
| preview\_post | Megmutatja, mi menne ki, csatornánként. Nem ír semmit. | no |
| list\_posts | A naptár, UTC és helyi idővel, csatornanévvel. | no |
| delete\_post | Nem közzétett poszt törlése. A már kint lévőt visszautasítja. | yes |
| create\_post | Piszkozat, ütemezés vagy azonnali közzététel. | yes |
| upload\_media\_from\_url | Kép vagy videó a médiatárba URL-ből vagy data URL-ből. | yes |
| create\_upload\_link | Böngészős link, amire a felhasználó ráhúzza a saját gépén lévő fájlt. Két óráig él. | yes |
| list\_upload\_link\_files | Ami a feltöltési linken beérkezett, a posztba tehető címmel. | no |

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](https://posty.hu/.well-known/mcp.json).

## Machine-readable

Every document an agent or a generator asks for:

- OpenAPI 3: [https://posty.hu/openapi.json](https://posty.hu/openapi.json)
- MCP manifest: [https://posty.hu/.well-known/mcp.json](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://posty.hu/llms.txt](https://posty.hu/llms.txt)

Get started today

## Grow your audience, not your workload

Posty brings your social accounts together in one calendar, so you can spend more time on your leads and your business. Don't let managing your accounts take up ten hours a week.

[Start your free trial](https://posty.hu/regisztracio)

7 days free · 0 Ft due today · cancel anytime