Ugrás a tartalomra
Claude-dal és ChatGPT-vel is működik

Sayweek API

Mindaz, amit a Sayweek tervez, megír és ütemez – a saját kódodból, n8n-ből, Zapierből, Make-ből vagy egy AI-asszisztensből. Az írás piszkozatot hoz létre, ami jóváhagyásra vár, így semmi nem kerül ki véletlenül.

Alap-URL: https://app.sayweek.com/api/v1

Első lépések

  1. Szerezz tokent

    Beállítások → Integrációk → REST API → „Új API-kulcs”. Válaszd ki a jogosultságokat; a kulcsot csak egyszer látod.

  2. Az első hívás

    A GET /me visszaadja a munkateret és a jogosultságokat – így ellenőrizheted a leggyorsabban a tokent.

  3. Építs

    Hozz létre piszkozatokat, olvasd a hetet, vagy iratkozz fel webhookokra. A jóváhagyás emberi döntés marad, hacsak nem engeded másképp.

Az első kérésed

curl
curl https://app.sayweek.com/api/v1/me \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
{
  "workspace": {
    "id": "w1",
    "name": "Acme Studio"
  },
  "auth": {
    "type": "api_key",
    "label": "CRM",
    "prefix": "pp_AbCd"
  },
  "user": null,
  "scopes": [
    "read",
    "write"
  ],
  "granted_scopes": [
    "read",
    "write"
  ],
  "webhook_events": [
    "post.created",
    "post.approved"
  ]
}

Hitelesítés

Minden kérést Authorization: Bearer fejléccel küldj. Kétféle token működik a /api/v1 minden végpontján:

API-kulcs (pp_…)

Saját szkriptekhez és szerverekhez. A Beállításokban hozod létre, a munkatérhez tartozik, a jogosultságokat létrehozáskor választod. Bármikor visszavonhatod.

OAuth access token (sw_at_…)

Olyan alkalmazásokhoz, amelyeket mások kapcsolnak össze („Csatlakozás a Sayweekhez”). 1 óráig érvényes, frissíthető, az engedélyező tag nevében működik – az ő szerepköre érvényes.

A Sayweek a kulcsokat és tokeneket csak hash-ként tárolja. Kiszivárgott egy token? Vond vissza a Beállításokban – azonnal leáll.

OAuth-alkalmazások

Authorization code folyamat PKCE-vel (S256) – szerveres, böngészős, mobil és parancssori alkalmazásokhoz egyaránt.

  1. Regisztráld az alkalmazást

    Beállítások → Integrációk → REST API → OAuth-alkalmazások: név, logó, visszairányítási címek és a kérhető jogosultságok. Szerveres alkalmazás client secretet kap; a nyilvános kliensek csak PKCE-t használnak.

  2. Küldd a felhasználót az engedélyező oldalra

    Készíts véletlen code_verifiert, és küldd el az SHA-256 lenyomatát (base64url) code_challenge-ként. A felhasználó a saját nyelvén látja a neved, a logód és a pontos jogosultságokat.

  3. Váltsd be a kódot

    POST /api/oauth/token: grant_type=authorization_code, a kód, a redirect_uri és a code_verifier (szerveres appnál + client_secret).

  4. Frissítés és visszavonás

    Az access token 1 óráig él. Frissíts grant_type=refresh_token-nel – a refresh token minden használatkor megújul. A POST /api/oauth/revoke megszünteti a kapcsolatot.

# 1) PKCE: a random verifier and its S256 challenge
CODE_VERIFIER=$(openssl rand -base64 48 | tr -d '=+/' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

# 2) Send the user here (they see your app's name, logo and the scopes)
open "https://app.sayweek.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID\
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=read%20write\
&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

Felderítés: /.well-known/oauth-authorization-server. A dinamikus kliensregisztráció (RFC 7591) az AI-asszisztenseknek nyitott; partneralkalmazást a Beállításokban regisztrálj, hogy a neve és a logója megjelenjen az engedélyező oldalon.

Jogosultságok

Egy token csak azt teheti, amit a jogosultságai engednek – és sosem többet, mint a tag szerepköre és a munkatér csomagja.

  • read

    Márkák, csatornák, heti terv, posztok, ötletek, naptár-összefoglaló, statisztika.

  • write

    Piszkozatok és ötletek írása, szerkesztése, hét generálása, el nem küldött poszt törlése, a token saját webhookjainak kezelése.

  • approve

    Jóváhagyás = valódi ütemezés. A munkatérben is engedélyezni kell, és minden jóváhagyási szabály érvényes.

Solo csomagban csak read; Pro, Team és Agency csomagban write és approve is.

Végpontok

Az OpenAPI-leírásból készül, ezért mindig egyezik az API-val. Minden kéréshez Bearer token kell.

Márkák és csatornák

GET/brandsread

Márkák a csatornáikkal

Paraméterek
limitquery1–200, alapból 50
cursorqueryAz előző oldal next_cursor értéke
curl "https://app.sayweek.com/api/v1/brands" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Példaválasz
{
  "data": [
    {
      "id": "b1",
      "name": "Acme Studio",
      "color": "#2563eb",
      "language": "en",
      "country": "GB",
      "is_business": true,
      "channels": [
        {
          "id": "0b6a5c4d-2e1f-4a3b-9c8d-7e6f5a4b3c2d",
          "name": "Acme on LinkedIn",
          "platform": "linkedin"
        }
      ]
    }
  ],
  "next_cursor": null
}
GET/channelsread

Csatornák

Paraméterek
brand_idqueryCsak ez a márka
limitquery1–200, alapból 50
cursorqueryAz előző oldal next_cursor értéke
curl "https://app.sayweek.com/api/v1/channels" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Posztok

GET/postsread

Posztok listája

Paraméterek
fromqueryÉÉÉÉ-HH-NN, alapból ma
toqueryÉÉÉÉ-HH-NN, alapból from + 30 nap (legfeljebb 366)
statusqueryVesszővel elválasztva: idea,draft,queued,approved,published,error
brand_idqueryCsak ez a márka
channel_idqueryCsak ez a csatorna
limitquery1–200, alapból 50
cursorqueryAz előző oldal next_cursor értéke
curl "https://app.sayweek.com/api/v1/posts?from=2026-10-12&to=2026-10-18&status=draft%2Capproved" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/postswrite

Piszkozat létrehozása (sosem tesz közzé)

Paraméterek
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/posts" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"0b6a5c4d-2e1f-4a3b-9c8d-7e6f5a4b3c2d","date":"2026-10-13","time":"09:30","text":"Three things a year of weekly posting taught us…","hashtags":["#marketing"]}'
Kérés törzse
{
  "channel_id": "0b6a5c4d-2e1f-4a3b-9c8d-7e6f5a4b3c2d",
  "date": "2026-10-13",
  "time": "09:30",
  "text": "Three things a year of weekly posting taught us…",
  "hashtags": [
    "#marketing"
  ]
}
Példaválasz
{
  "id": "6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f",
  "status": "draft",
  "date": "2026-10-13",
  "time": "09:30",
  "timezone": "Europe/London",
  "channel": {
    "id": "0b6a5c4d-2e1f-4a3b-9c8d-7e6f5a4b3c2d",
    "name": "Acme on LinkedIn",
    "platform": "linkedin"
  },
  "text": "Three things a year of weekly posting taught us…",
  "hashtags": [
    "#marketing"
  ],
  "submitted_for_approval": false
}
GET/posts/{id}read

Egy poszt (jóváhagyási ellenőrzéssel)

Paraméterek
idpathkötelezőAzonosító (UUID)
curl "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
PATCH/posts/{id}write

Még nem jóváhagyott poszt szövegének vagy időpontjának módosítása

Paraméterek
idpathkötelezőAzonosító (UUID)
curl -X PATCH "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Three things a year of weekly posting taught us (and one we unlearned).","time":"10:00"}'
Kérés törzse
{
  "text": "Three things a year of weekly posting taught us (and one we unlearned).",
  "time": "10:00"
}
DELETE/posts/{id}write

Poszt törlése (megjelentet nem; jóváhagyotthoz `approve` kell)

Paraméterek
idpathkötelezőAzonosító (UUID)
curl -X DELETE "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/posts/{id}/approveapprove

Jóváhagyás – a posztot valóban beütemezi

Kell hozzá az `approve` jogosultság és a Beállítások → Integrációk → AI-asszisztensek → „Jóváhagyás engedélyezése”. Minden jóváhagyási szabály érvényes; kétlépcsős jóváhagyásnál a nem tulajdonos csak beküldi a posztot.

Paraméterek
idpathkötelezőAzonosító (UUID)
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f/approve" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Példaválasz
{
  "result": "scheduled",
  "post": {
    "id": "6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f",
    "status": "queued"
  }
}
DELETE/posts/{id}/approveapprove

Jóváhagyás visszavonása (visszavonás gomb)

A jóváhagyott vagy sorban álló poszt visszakerül piszkozatba (`result: revoked`): az ütemezés törlődik a Postizban vagy a Sayweek saját sorában, és a még ki nem ment keresztposztok is visszakerülnek. A nem tulajdonos jóváhagyásával csak a tulajdonosoknak beküldött piszkozatnál a beküldés visszavonódik (`result: withdrawn`). Megjelent vagy épp küldés alatti posztnál (TikTok / YouTube feldolgozás, kiment szálrész) 409, ha nincs mit visszavonni, 422. Ugyanaz a jogosultság és munkaterület-kapcsoló kell, mint a jóváhagyáshoz.

Paraméterek
idpathkötelezőAzonosító (UUID)
curl -X DELETE "https://app.sayweek.com/api/v1/posts/{id}/approve" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/posts/{id}/photowrite

A poszt fotójának beállítása egy képből

A poszt (első) fotóját a megadott JPEG, PNG vagy WebP képre cseréli (base64 az `image` mezőben, legfeljebb 3 MB képadat; az EXIF- és helyadatok törlődnek, újrakódolva), és a poszt nyitott fotókérését késznek jelöli. Ugyanaz az állapotszabály, mint a szerkesztőben: piszkozat, illetve jóváhagyott poszt nem sokkal a megjelenés előttig (újraszinkronizálva az ütemezőhöz; ehhez `approve` jogosultság is kell); különben 409. Az `undo` csak akkor van kitöltve, ha a posztnak nem volt fotója, és még nincs beütemezve.

Paraméterek
idpathkötelezőAzonosító (UUID)
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/posts/{id}/photo" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Kérés törzse
{}
DELETE/posts/{id}/photowrite

Feltöltött fotó visszavonása

Eltávolítja a `media_id` által megadott fotót (a feltöltés `undo` értékéből), amíg a poszt nincs beütemezve, és újra megnyitja a fotókérését. 409, ha a poszt be van ütemezve vagy megjelent, vagy a fotót azóta lecserélték.

Paraméterek
idpathkötelezőAzonosító (UUID)
media_idqueryA feltöltés undo.media_id értéke
curl -X DELETE "https://app.sayweek.com/api/v1/posts/{id}/photo" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/posts/{id}/movewrite

Poszt áthelyezése másik napra vagy időpontra (a naptár áthelyezése)

Add meg a `date` (+ `time`) mezőt – a szerző aznapi helyi ideje, mint a naptárban –, vagy `timezone`-nal együtt (az eszköz zónája, átszámolva), vagy egy pontos `scheduled_at`-et eltolással. Az adott zónában nem létező időpontot (nyári időszámítás) elutasítjuk. Szabályütközésnél (egy nap egy poszt, túl közel, rossz nap, túl sok, tiltott nap) `moved: false` és `warnings` jön; `force: true`-val küldd újra a megerősítéshez. Megjelent, épp küldés alatti vagy múltbeli célnál `moved: false` és `block` jön. Jóváhagyott vagy sorban álló posztot a Postizban is átütemezünk, ehhez `approve` jogosultság kell. Az `If-Match: "<updated_at>"` feltételessé teszi (409, ha a poszt közben változott).

Paraméterek
idpathkötelezőAzonosító (UUID)
If-MatchheaderA poszt updated_at értéke, idézőjelben
curl -X POST "https://app.sayweek.com/api/v1/posts/{id}/move" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Kérés törzse
{}

Ötletek

GET/ideasread

Az ötletláda

Paraméterek
statusquerynew (alap), placed, dismissed, all
limitquery1–200, alapból 50
cursorqueryAz előző oldal next_cursor értéke
curl "https://app.sayweek.com/api/v1/ideas?status=new" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/ideaswrite

Ötlet hozzáadása

Paraméterek
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/ideas" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"A customer asked how we price small retainers – worth a post."}'
Kérés törzse
{
  "text": "A customer asked how we price small retainers – worth a post."
}
Példaválasz
{
  "ok": true,
  "id": "c2d3e4f5-0a1b-4c2d-8e3f-405162738495",
  "text": "A customer asked how we price small retainers – worth a post.",
  "status": "new",
  "suggestions": []
}

Tervezés és generálás

GET/weekread

Heti terv: minden idősáv a posztjával

Paraméterek
startqueryA hét bármelyik napja (alapból ez a hét)
brand_idqueryCsak ez a márka
curl "https://app.sayweek.com/api/v1/week?start=2026-10-12" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/generatewrite

Piszkozatok generálása egy időszakra (aszinkron)

Minden szabad idősávba piszkozatot sorol be (alapból a következő hétfő–vasárnap), és egy feladatot ad vissza. Kérdezd le: GET /jobs/{id}.

Paraméterek
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/generate" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-12","to":"2026-10-18"}'
Kérés törzse
{
  "from": "2026-10-12",
  "to": "2026-10-18"
}
Példaválasz
{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "queued",
  "from": "2026-10-12",
  "to": "2026-10-18",
  "total": 5,
  "done": 0,
  "failed": 0,
  "pending": 5,
  "skipped": 0,
  "posts": []
}
GET/jobs/{id}read

Egy generálási feladat állapota

Paraméterek
idpathkötelezőAzonosító (UUID)
curl "https://app.sayweek.com/api/v1/jobs/a1b2c3d4-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Naptár és statisztika

GET/calendar/sourcesread

Összekötött naptárak és amit a Sayweek kiolvasott belőlük (város, nap típusa)

Paraméterek
daysquery1–60, alapból 14
curl "https://app.sayweek.com/api/v1/calendar/sources?days=14" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
GET/analytics/summaryread

Statisztikai összefoglaló

Paraméterek
daysquery7, 30 (alap) vagy 90
curl "https://app.sayweek.com/api/v1/analytics/summary?days=30" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Fiók és webhookok

GET/meread

Kié ez a token (kapcsolat tesztelése)

curl "https://app.sayweek.com/api/v1/me" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Példaválasz
{
  "workspace": {
    "id": "w1",
    "name": "Acme Studio"
  },
  "auth": {
    "type": "api_key",
    "label": "CRM",
    "prefix": "pp_AbCd"
  },
  "user": null,
  "scopes": [
    "read",
    "write"
  ],
  "granted_scopes": [
    "read",
    "write"
  ],
  "webhook_events": [
    "post.created",
    "post.approved"
  ]
}
GET/webhooksread

A token webhook-feliratkozásai

curl "https://app.sayweek.com/api/v1/webhooks" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/webhookswrite

URL feliratkoztatása eseményekre (a titkot egyszer adjuk vissza)

Csak https, csak nyilvános cím (nem belső / helyi), 443, 8443, 80 vagy 8080 port. A kézbesítést egyre hosszabb szünetekkel kb. másfél napig próbáljuk újra; az egy napja hibázó végpontot kikapcsoljuk.

Paraméterek
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/webhooks" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/sayweek","events":["post.approved","post.published"],"description":"CRM sync"}'
Kérés törzse
{
  "url": "https://example.com/hooks/sayweek",
  "events": [
    "post.approved",
    "post.published"
  ],
  "description": "CRM sync"
}
Példaválasz
{
  "id": "d4c3b2a1-0000-4000-8000-000000000002",
  "url": "https://example.com/hooks/sayweek",
  "description": "CRM sync",
  "events": [
    "post.approved",
    "post.published"
  ],
  "enabled": true,
  "disabled_reason": null,
  "last_status": null,
  "last_delivery_at": null,
  "created_at": "2026-10-05T09:00:00.000Z",
  "secret": "whsec_…"
}
GET/webhooks/{id}read

Egy webhook-feliratkozás

Paraméterek
idpathkötelezőAzonosító (UUID)
curl "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
PATCH/webhooks/{id}write

Webhook-feliratkozás módosítása

Csak az elküldött mezők változnak. Az új URL-t ugyanúgy ellenőrizzük, mint létrehozáskor; az `enabled: true` újra bekapcsolja a szüneteltetett vagy hibák miatt kikapcsolt végpontot, és nullázza a hibasorozatot. A titok nem változik.

Paraméterek
idpathkötelezőAzonosító (UUID)
curl -X PATCH "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"events":["post.approved","post.published","post.failed"],"enabled":true}'
Kérés törzse
{
  "events": [
    "post.approved",
    "post.published",
    "post.failed"
  ],
  "enabled": true
}
Példaválasz
{
  "id": "d4c3b2a1-0000-4000-8000-000000000002",
  "url": "https://example.com/hooks/sayweek",
  "description": "CRM sync",
  "events": [
    "post.approved",
    "post.published",
    "post.failed"
  ],
  "enabled": true,
  "disabled_reason": null,
  "last_status": 200,
  "last_delivery_at": "2026-10-05T09:12:00.000Z",
  "created_at": "2026-10-05T09:00:00.000Z"
}
DELETE/webhooks/{id}write

Leiratkozás

Paraméterek
idpathkötelezőAzonosító (UUID)
curl -X DELETE "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/webhooks/{id}/testwrite

Aláírt próbaesemény küldése most

Paraméterek
idpathkötelezőAzonosító (UUID)
curl -X POST "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002/test" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Példaválasz
{
  "delivered": true,
  "status": 200,
  "duration_ms": 182,
  "response": "ok"
}

Nap és teendők

GET/agendaread

Posztok és fotó-javaslatok naponként, a te időzónádban

A napokat a `tz` (az eszköz IANA-időzónája; alapból a munkaterület otthoni zónája) szerint vágjuk: egy poszt arra a napra kerül, amelyre az időpontja ott esik, a `source` pedig megőrzi a saját helyi idejét és zónáját. A keresztposztok a fő poszt alá kerülnek (`sibling_channels`). A fotó-javaslatok egész napos elemek. Legfeljebb 31 nap.

Paraméterek
fromqueryÉÉÉÉ-HH-NN a tz szerint, alapból ma
toqueryÉÉÉÉ-HH-NN a tz szerint, alapból from + 6 nap
tzqueryIANA-időzóna, pl. Europe/Budapest
brand_idqueryCsak ez a márka
curl "https://app.sayweek.com/api/v1/agenda" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
GET/todosread

A token gazdájának Sayweek-teendői

Minden hívásnál újraszámolva (soha nincs tárolva): jóváhagyások, hiányzó videók, a heti interjú, lejáró kapcsolatok, sikertelen posztok, ütközések és üres helyek. Egy teendő akkor tűnik el, ha a munka elkészül a Sayweekben – az API-n nem lehet kipipálni, csak elhalasztani. A `key` stabil; a `fingerprint` változik, ha a szöveg vagy a határidő változik; a felső szintű `fingerprint` az egész listára vonatkozik (vesd össze a `todos.changed` webhookkal). Személyhez kötött token kell (OAuth, vagy valaki által létrehozott API-kulcs).

Paraméterek
tzqueryIANA-időzóna a due_date-hez, alapból a munkaterületé
snoozedqueryinclude (alap) vagy exclude
curl "https://app.sayweek.com/api/v1/todos" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/todos/{key}/snoozewrite

Teendő elhalasztása (semmit nem hagy jóvá, nem pipál ki)

Paraméterek
keypathkötelezőA teendő kulcsa, pl. approve:2026-W47 (a kettőspont lehet százalékkódolt)
Idempotency-Keyheader24 órán át visszajátssza az első választ (ugyanaz a kulcs + ugyanaz a kérés)
curl -X POST "https://app.sayweek.com/api/v1/todos/{key}/snooze" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Kérés törzse
{}
DELETE/todos/{key}/snoozewrite

Halasztás visszavonása

Paraméterek
keypathkötelező
curl -X DELETE "https://app.sayweek.com/api/v1/todos/{key}/snooze" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Kipróbálás

Hívd az API-t itt, a saját fiókoddal – nem kell kulcsot másolnod. A konzol 1 órás tokent kap ahhoz a munkatérhez, amelyikbe beléptél; approve jogosultságot sosem kap.

Webhookok

Ha történik valami, a Sayweek aláírt JSON-eseményt küld (POST) a HTTPS-végpontodra. Végpontot a Beállítások → Integrációk → Webhookok alatt adhatsz hozzá, vagy kódból a POST /webhooks hívással.

Események

post.createdPoszt létrejöttÚj piszkozat vagy ötlet egy idősávban
approval.requestedJóváhagyásra várEgy piszkozat jóváhagyásra kész
post.approvedPoszt jóváhagyvaValaki jóváhagyta a posztot
post.scheduledPoszt ütemezveA poszt be van időzítve a közösségi oldalra
post.publishedPoszt megjelentA poszt kiment
post.failedKiküldés sikertelenA poszt nem ment ki
idea.createdÚj ötletÖtlet érkezett az ötletládába
comment.receivedÚj hozzászólásValaki hozzászólt egy megjelent poszthoz
review.commentÜgyfél-visszajelzésMegjegyzés a jóváhagyási linken
todos.changedTeendők változtakEgy személy Sayweek-teendői változtak (csak API/OAuth-feliratkozásnak, a saját felhasználójáról)

Tartalom

HTTP
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Sayweek-Webhooks/1.0
X-Sayweek-Event: post.approved
X-Sayweek-Delivery: <delivery id>
Sayweek-Event-Id: evt_3m9QeX2a7bKfT1
Sayweek-Timestamp: 1791797462
Sayweek-Signature: t=1791797462,v1=5f2b…c09e

{
  "id": "evt_3m9QeX2a7bKfT1",
  "event": "post.approved",
  "api_version": "2026-10-05",
  "created_at": "2026-10-12T07:31:02.000Z",
  "at": "2026-10-12T07:31:02.000Z",
  "workspace_id": "8a1f0c4e-…",
  "data": {
    "postId": "6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f",
    "date": "2026-10-12",
    "time": "09:30",
    "text": "Three things a year of weekly posting taught us…"
  }
}

Az aláírás ellenőrzése

Minden kézbesítésben van Sayweek-Signature fejléc: t=<unix másodperc>,v1=<a „t.nyers törzs” hex HMAC-SHA256 értéke a titkoddal>. Állandó idejű összehasonlítással ellenőrizd, és dobd el az 5 percnél régebbi időbélyeget – ez véd a visszajátszás ellen.

import { createHmac, timingSafeEqual } from "node:crypto";

// Use the RAW request body (before JSON.parse).
export function verifySayweek(secret, rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay protection
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === expected.length && timingSafeEqual(got, Buffer.from(expected));
}

Újrapróbálás, napló, automatikus kikapcsolás

  • 8 másodpercen belüli bármilyen 2xx válasz kézbesítettnek számít. Időtúllépésnél, hálózati hibánál, 408, 409, 425, 429 és 5xx válasznál egyre hosszabb szünetekkel újrapróbáljuk (legfeljebb 8-szor, nagyjából 30 órán át); a többi 4xx válasz végleges. Az esemény azonosítója ugyanaz marad, így kiszűrheted az ismétlést.
  • Minden próbálkozás látszik a kézbesítési naplóban (Beállítások → Webhookok → Kézbesítési napló) az állapottal, az idővel és a válaszod első soraival – és egy kattintással újraküldhető.
  • Ha egy végpont egy napon át folyamatosan hibázik, automatikusan kikapcsoljuk, és a munkatér tulajdonosai értesítést kapnak. Javítsd, majd kapcsold vissza.
  • Csak nyilvános https:// cím fogadható el – a belső, loopback és link-local IP-ket letiltjuk, mentéskor és minden kézbesítésnél újra ellenőrizve. Átirányítást nem követünk.

Claude és ChatGPT

A Sayweek távoli MCP-szerver (Streamable HTTP, OAuth 2.1) – add hozzá a Claude-hoz vagy a ChatGPT-hez ezzel a címmel:

MCP
https://app.sayweek.com/api/mcp
  • claude.ai: Beállítások → Connectors → „Add custom connector” → illeszd be a címet → Connect → lépj be → Engedélyezés.
  • ChatGPT: Beállítások → Apps & Connectors → Advanced → Developer mode → Create → a cím, Authentication: OAuth.

Claude Code:

shell
claude mcp add --transport http sayweek https://app.sayweek.com/api/mcp

Korlátok

A korlátok tokenenként és percenként értendők. Túllépéskor 429-es választ kapsz Retry-After fejléccel (másodpercben).

120 / perc

Olvasás (GET)

30 / perc

Írás (POST, PATCH, DELETE)

6 / perc

Generálás (POST /generate)

Biztonságos újrapróbálás: POST-nál az Idempotency-Key fejléc 24 órán át visszajátssza az első választ. A listák lapozhatók: { data, next_cursor } – a következő oldal: ?cursor=.

Hibák

A hibák mindig ugyanígy néznek ki; a code állandó, a message embereknek szól.

JSON
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the \"write\" scope.",
    "details": {
      "required": "write",
      "granted": [
        "read"
      ]
    }
  }
}
401unauthorizedHiányzó, ismeretlen, lejárt vagy visszavont token.
403insufficient_scopeA tokennek nincs meg a jogosultsága (details.required).
403plan_requiredA munkatér csomagja ezt nem tartalmazza.
403approvals_disabledA munkatérben ki van kapcsolva az API-n keresztüli jóváhagyás.
404not_foundNincs ilyen elem ebben a munkatérben.
400invalid_requestEgy paraméter vagy a törzs hibás (a details megmondja, melyik).
409conflictAz elem megváltozott, vagy olyan állapotban van, ami ezt nem engedi.
422idempotency_mismatchEzt az Idempotency-Key-t egy másik kéréshez már használtad.
429rate_limitedTúl sok kérés – várj Retry-After másodpercet.
500internalA mi hibánk. Próbáld újra később; már tudunk róla.

SDK-k és eszközök

Kész építőkockák – mind ugyanabból az OpenAPI-leírásból.

Változásnapló

  1. Webhookok aláírt, újrapróbált kézbesítéssel és naplóval; /webhooks és /me végpont; OAuth-alkalmazások saját arculatú engedélyező oldallal; kipróbáló konzol; Postman-gyűjtemény, n8n node, JS- és Python-kliens.

  2. API v1: márkák, csatornák, posztok, ötletek, hét, generálás, naptár, statisztika; MCP-szerver a Claude-hoz és a ChatGPT-hez; OAuth 2.1 PKCE-vel.

Fejlesztőknek: API és MCP (Claude, ChatGPT) – Sayweek