NaptárAI API, MCP és CLI referencia

Ez az oldal a NaptárAI programozható felületeinek teljes referenciája: minden nyilvános REST-végpont, a parancssori eszköz összes parancsa, és az MCP-szerver eszközei. Ha még nem döntötted el, melyik felület kell, a fejlesztői áttekintés onnan indul.

Végpontonként külön oldal, paraméterekkel és futtatható példákkal, a teljes dokumentációban van: naptarai.hu/dokumentacio/api/vegpontok.

Hogyan működik

A NaptárAI három felületen ugyanazt a munkaterületet kezeli, mint a webes felület. A REST API a saját kódodból, a parancssori eszköz a terminálból és a szkriptjeidből, az MCP-szerver pedig egy AI-ügynökből. Mindhárom ugyanazokat a jogosultságokat és korlátokat használja, ezért amit az egyiken megtehetsz, megteheted a másikon is.

A REST API alapcíme https://naptarai.hu/api/public/v1. A verzió az útvonalban van, és minden válasz JSON.

Csatlakozás három lépésben

1. Regisztrálj a naptarai.hu/regisztracio címen. Nincs értékesítési hívás, nincs várólista.
2. Kösd be legalább egy közösségi fiókodat a felületen. Ezt a lépést API-ból nem lehet elvégezni, mert a platform beleegyezést kér egy embertől.
3. Hozz létre magadnak egy kulcsot: Beállítások → Fejlesztők. A kulcs egyszer látszik, a létrehozás pillanatában.

Az első hívásod ellenőrizheti, hogy minden a helyén van. Ez a végpont kulcs nélkül is válaszol, és megmondja, hol találsz meg mindent:

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

Az első hitelesített hívás pedig a platformjaidat listázza:

curl https://naptarai.hu/api/public/v1/integrations \
  -H "Authorization: psty_a_kulcsod"

Hitelesítés

Kétféle hitelesítő adat működik. Az API-kulcs a teljes Authorization fejléc értéke (psty_…), és a saját kódodhoz való. Az OAuth 2.1 hozzáférési token (Bearer pos_…) akkor kell, ha egy másik alkalmazás a te felhasználóid nevében fér hozzá a NaptárAI-hoz; a folyamat PKCE-vel megy, a metaadatok pedig géppel olvashatók.

Egy kulcs jogosultsága a tulajdonosa aktuális szerepkörével mozog: ha valaki lefokozódik vagy kikerül a munkaterületről, a kulcsa azonnal annyit tud, amennyit ő. Ha egy kulcs több munkaterülethez tartozik, a showorg fejléc választ közülük.

Végpontok

Minden útvonal a https://naptarai.hu/api/public/v1 alatt van. A „Jogosultság" oszlop azt mutatja, milyen scope kell a kulcsra; ha hiányzik, a válasz 403, és megnevezi a hiányzót.

A pontos kérés- és válaszsémákat, mezőnként, az OpenAPI 3 leírás tartalmazza. Abból ügyfélkódot is tudsz generáltatni.

Példa: REST-hívás

A dátum mindig UTC, ISO 8601 formátumban. A type lehet draft, schedule vagy now.

curl -X POST https://naptarai.hu/api/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_platform_azonositoja" },
      "value": [{ "content": "<p>Sziasztok!</p>" }]
    }]
  }'

A válasz platformonként egy sort ad vissza, benne a postId értékkel, amit a törléshez és az állapotváltáshoz használsz.

Hibák

Minden hiba JSON. A NaptárAI által kiváltott hibákban a msg mező hordozza az emberi mondatot; a kérés formai ellenőrzésén elbukó hívások a keretrendszer alakját kapják (statusCode, message, error). A jogosultsági 403 megnevezi a hiányzó scope-ot és a kulcstulajdonos szerepkörét, mert a leggyakoribb ok nem a rossz kulcs, hanem a lefokozott felhasználó.

A státuszkód mondja meg, érdemes-e újrapróbálni: a 400, 401, 403 és 404 addig nem múlik el, amíg nem változtatsz valamin; a 429 és az 5xx igen. Az ApiError séma mindezt géppel olvashatóan is leírja az OpenAPI dokumentumban.

Hívási korlátok

Minden válasz viszi a RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (másodpercben, nem időbélyeg) és RateLimit-Policy fejléceket. A 429 mellé Retry-After is érkezik. Minden útvonalnak külön kerete van, kulcsonként. Ne a 429-re várj: a maradék értékből előre tudsz lassítani.

Verziózás és kivezetés

A verzió az útvonalban van: minden nyilvános hívás a /public/v1 alatt él. Törő változás új verzióként jelenne meg (/public/v2), a v1 pedig tartja a szerződését. Bővítés , új opcionális mező, új útvonal, új felsorolt érték, a v1-en belül történik, ezért a kódod hagyja figyelmen kívül azokat a mezőket, amiket nem ismer.

Ha egy útvonalat kivezetnénk, a válasza Deprecation: true fejlécet kap, mellé Sunset fejlécben a dátumot, ami után már nem működik. Ez a dátum soha nem lehet közelebb 180 napnál. Minden válasz visz egy Link fejlécet is rel="sunset" kapcsolattal, ami erre a szakaszra mutat. Jelenleg semmi nincs kivezetés alatt.

Parancssori eszköz

A parancs neve szh, ugyanezt az API-t használja terminálból. A kézikönyv a dokumentációban van. Az npm-csomag még nincs kiadva. Belépés:

szh auth:login
szh integrations:list

A bejelentkezés böngészőt nyit, a kulcsot pedig a gépeden tárolja, így a szkriptjeidbe nem kell beleírnod. Minden parancs tud --json kimenetet adni, ami gépi feldolgozásra való.

MCP-szerver

Az MCP-szerver címe https://naptarai.hu/api/mcp-oauth, streamable HTTP átvitellel, OAuth 2.1 hitelesítéssel. Az ügynököd ezeket az eszközöket látja:

A kapcsolat hitelesítést kér: hitelesítő adat nélkül a szerver 401-et ad, és a WWW-Authenticate fejlécben megmondja, hol lehet engedélyt kérni. Ez nem hiba, hanem az MCP szabvány szerinti folyamat kezdete. Az eszközök listája ettől függetlenül olvasható a manifesztből.

Gépi olvasásra

Minden dokumentum, amit egy ügynök vagy egy generátor kér:

• OpenAPI 3: https://naptarai.hu/openapi.json
• MCP manifeszt: https://naptarai.hu/.well-known/mcp.json
• Állapot és felderítés: https://naptarai.hu/api/public/v1/status
• OAuth metaadatok: https://naptarai.hu/api/.well-known/oauth-protected-resource
• Rövid összefoglaló ügynököknek: https://naptarai.hu/llms.txt