Skip to content
Works with Claude & ChatGPT

Sayweek API

Everything Sayweek can plan, draft and schedule – from your own code, n8n, Zapier, Make or an AI assistant. Writes create drafts that wait for approval, so nothing goes public by accident.

Base URL: https://app.sayweek.com/api/v1

Getting started

  1. Get a token

    Settings → Integrations → REST API → “New API key”. Choose the scopes; the key is shown once.

  2. Make your first call

    GET /me answers with the workspace and the scopes – the quickest way to check the token.

  3. Build

    Create drafts, read the week, or subscribe to webhooks. Approving stays a human decision unless you allow it.

Your first request

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"
  ]
}

Authentication

Send every request with an Authorization: Bearer header. Two kinds of token work everywhere in /api/v1:

API key (pp_…)

For your own scripts and servers. Created in Settings, tied to the workspace, scopes chosen at creation. Revoke it any time.

OAuth access token (sw_at_…)

For apps other people connect (“Connect to Sayweek”). Valid for 1 hour, refreshable, on behalf of the member who allowed it – their role still applies.

Sayweek stores only hashes of keys and tokens. A leaked token? Revoke it in Settings – it stops working immediately.

OAuth apps

Authorization code flow with PKCE (S256) – for server apps, single-page apps, mobile apps and CLIs alike.

  1. Register the app

    Settings → Integrations → REST API → OAuth apps: name, logo, redirect URLs and the scopes it may ask for. Server apps get a client secret; public clients use PKCE alone.

  2. Send the user to the consent screen

    Create a random code_verifier, send its SHA-256 (base64url) as code_challenge. The user sees your name, logo and the exact permissions, in their language.

  3. Exchange the code

    POST /api/oauth/token with grant_type=authorization_code, the code, redirect_uri and code_verifier (+ client_secret for server apps).

  4. Refresh and revoke

    Access tokens last 1 hour. Use grant_type=refresh_token – the refresh token rotates on every use. POST /api/oauth/revoke ends the connection.

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

Discovery: /.well-known/oauth-authorization-server. Dynamic client registration (RFC 7591) is open for AI assistants; partner apps should be registered in Settings so their name and logo appear on the consent screen.

Scopes

A token can only do what its scopes allow – and never more than the member’s role and the workspace’s plan.

  • read

    Brands, channels, the week plan, posts, ideas, calendar summary, analytics.

  • write

    Create and edit drafts and ideas, generate a week, delete unsent posts, manage the token’s own webhooks.

  • approve

    Approve = schedule for real. Must also be allowed in the workspace; every approval rule applies.

Solo: read only. Pro, Team and Agency: write and approve too.

Endpoint reference

Generated from the OpenAPI description, so it always matches the API. Every request needs a Bearer token.

Brands & channels

GET/brandsread

List brands with their channels

Parameters
limitquery1–200, default 50
cursorquerynext_cursor of the previous page
curl "https://app.sayweek.com/api/v1/brands" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Example response
{
  "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

List channels

Parameters
brand_idqueryOnly this brand
limitquery1–200, default 50
cursorquerynext_cursor of the previous page
curl "https://app.sayweek.com/api/v1/channels" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Posts

GET/postsread

List posts

Parameters
fromqueryYYYY-MM-DD, default today
toqueryYYYY-MM-DD, default from + 30 days (max 366)
statusqueryComma separated: idea,draft,queued,approved,published,error
brand_idqueryBrand filter
channel_idqueryChannel filter
limitquery1–200, default 50
cursorquerynext_cursor of the previous page
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

Create a draft (never publishes)

Parameters
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
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"]}'
Request body
{
  "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"
  ]
}
Example response
{
  "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

Get a post (with approval check)

Parameters
idpathrequired
curl "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
PATCH/posts/{id}write

Update text or schedule of a not-yet-approved post

Parameters
idpathrequired
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"}'
Request body
{
  "text": "Three things a year of weekly posting taught us (and one we unlearned).",
  "time": "10:00"
}
DELETE/posts/{id}write

Delete a post (not published ones; approved ones need `approve`)

Parameters
idpathrequired
curl -X DELETE "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/posts/{id}/approveapprove

Approve – schedules the post for real

Needs the `approve` scope and Settings → Integrations → AI assistants → “Allow approvals”. All approval rules apply; with two-step approval a non-owner only submits the post.

Parameters
idpathrequired
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
curl -X POST "https://app.sayweek.com/api/v1/posts/6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f/approve" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Example response
{
  "result": "scheduled",
  "post": {
    "id": "6f1c2b0e-3a4d-4c5e-9f60-1a2b3c4d5e6f",
    "status": "queued"
  }
}
DELETE/posts/{id}/approveapprove

Take an approval back (undo)

An approved or queued post goes back to a draft (`result: revoked`): its schedule is cancelled in Postiz or in Sayweek's own queue, and unsent cross-post siblings go back too. A draft that a non-owner's approval only submitted to the owners has the submission withdrawn (`result: withdrawn`). A published post, or one already being sent (TikTok / YouTube processing, a thread part out), answers 409; a post with nothing to take back answers 422. Same scope and workspace switch as approving.

Parameters
idpathrequired
curl -X DELETE "https://app.sayweek.com/api/v1/posts/{id}/approve" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/posts/{id}/photowrite

Set the post's photo from an image

Replaces the post's (first) photo with the given JPEG, PNG or WebP (base64 in `image`, at most 3 MB of image bytes; EXIF / location stripped, re-encoded) and marks the post's open photo prompt done. Same status rule as the editor: drafts, and an approved post until shortly before it goes out (it is re-synced to the scheduler; that needs the `approve` scope too); otherwise 409. `undo` is set only when the post had no photo and is not scheduled yet.

Parameters
idpathrequired
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
curl -X POST "https://app.sayweek.com/api/v1/posts/{id}/photo" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body
{}
DELETE/posts/{id}/photowrite

Take an uploaded photo back (undo)

Removes the photo given by `media_id` (from the upload's `undo`) while the post is not scheduled yet, and opens its photo prompt again. 409 when the post is scheduled / published or the photo was replaced since.

Parameters
idpathrequired
media_idqueryThe upload's undo.media_id
curl -X DELETE "https://app.sayweek.com/api/v1/posts/{id}/photo" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/posts/{id}/movewrite

Move a post to another day or time (the calendar's move)

Give `date` (+ `time`) – the wall-clock time where the author is that day, like the calendar – or with `timezone` (the device's zone, converted), or an exact `scheduled_at` with an offset. A time that doesn't exist in that zone (daylight saving gap) is refused. Rule clashes (one per day, too close, wrong weekday, too many, blocked day) answer `moved: false` with `warnings`; resend with `force: true` to confirm. Published, sending or past targets answer `moved: false` with `block`. Approved or queued posts are rescheduled in Postiz too and need the `approve` scope. `If-Match: "<updated_at>"` makes the move conditional (409 when the post changed).

Parameters
idpathrequired
If-MatchheaderThe post's updated_at, quoted
curl -X POST "https://app.sayweek.com/api/v1/posts/{id}/move" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body
{}

Ideas

GET/ideasread

List the ideas box

Parameters
statusquerynew (default), placed, dismissed, all
limitquery1–200, default 50
cursorquerynext_cursor of the previous page
curl "https://app.sayweek.com/api/v1/ideas?status=new" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/ideaswrite

Add an idea

Parameters
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
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."}'
Request body
{
  "text": "A customer asked how we price small retainers – worth a post."
}
Example response
{
  "ok": true,
  "id": "c2d3e4f5-0a1b-4c2d-8e3f-405162738495",
  "text": "A customer asked how we price small retainers – worth a post.",
  "status": "new",
  "suggestions": []
}

Planning & generation

GET/weekread

Week plan: every slot with its post

Parameters
startqueryAny date of the week (default: this week)
brand_idqueryBrand filter
curl "https://app.sayweek.com/api/v1/week?start=2026-10-12" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/generatewrite

Generate drafts for a date range (async)

Queues a draft for every open slot (default: next Monday–Sunday) and returns a job. Poll GET /jobs/{id}.

Parameters
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
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"}'
Request body
{
  "from": "2026-10-12",
  "to": "2026-10-18"
}
Example response
{
  "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

Status of a generate job

Parameters
idpathrequired
curl "https://app.sayweek.com/api/v1/jobs/a1b2c3d4-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Calendar & analytics

GET/calendar/sourcesread

Connected calendars and what Sayweek derived (city, kind of day)

Parameters
daysquery1–60, default 14
curl "https://app.sayweek.com/api/v1/calendar/sources?days=14" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
GET/analytics/summaryread

Analytics summary

Parameters
daysquery7, 30 (default) or 90
curl "https://app.sayweek.com/api/v1/analytics/summary?days=30" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Account & webhooks

GET/meread

Who this token belongs to (test connection)

curl "https://app.sayweek.com/api/v1/me" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Example response
{
  "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

List this token's webhook subscriptions

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

Subscribe a URL to events (the secret is returned once)

https only, public hosts only (no private / local addresses), ports 443, 8443, 80, 8080. Deliveries are retried with exponential back-off for ~1.5 days; an endpoint failing for a day is switched off.

Parameters
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
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"}'
Request body
{
  "url": "https://example.com/hooks/sayweek",
  "events": [
    "post.approved",
    "post.published"
  ],
  "description": "CRM sync"
}
Example response
{
  "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

Get a webhook subscription

Parameters
idpathrequired
curl "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
PATCH/webhooks/{id}write

Update a webhook subscription

Only the fields you send change. A new url is checked like on create; `enabled: true` switches a paused or failed endpoint on again and clears its failure streak. The secret stays the same.

Parameters
idpathrequired
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}'
Request body
{
  "events": [
    "post.approved",
    "post.published",
    "post.failed"
  ],
  "enabled": true
}
Example response
{
  "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

Unsubscribe

Parameters
idpathrequired
curl -X DELETE "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/webhooks/{id}/testwrite

Send a signed ping event now

Parameters
idpathrequired
curl -X POST "https://app.sayweek.com/api/v1/webhooks/d4c3b2a1-0000-4000-8000-000000000002/test" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
Example response
{
  "delivered": true,
  "status": 200,
  "duration_ms": 182,
  "response": "ok"
}

Day & to-dos

GET/agendaread

Posts and photo prompts per day, in your time zone

Days are cut in `tz` (the device's IANA zone; default: the workspace's home zone): a post lands on the day its moment falls on there, `source` keeps its own wall-clock time and zone. Cross-posts are folded into their lead (`sibling_channels`). Photo prompts are all-day items. At most 31 days.

Parameters
fromqueryYYYY-MM-DD in tz, default today
toqueryYYYY-MM-DD in tz, default from + 6 days
tzqueryIANA time zone, e.g. Europe/Budapest
brand_idqueryOnly this brand
curl "https://app.sayweek.com/api/v1/agenda" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
GET/todosread

What the token's person has to do in Sayweek

Computed on every call (never stored): approvals, missing videos, the weekly interview, expiring connections, failed posts, clashes and empty slots. A to-do disappears when the work is done in Sayweek – it can't be ticked off through the API, only snoozed. `key` is stable; `fingerprint` changes when the text or due date does; the top-level `fingerprint` covers the whole list (compare it with the `todos.changed` webhook). Needs a token tied to a person (OAuth, or an API key created by someone).

Parameters
tzqueryIANA time zone for due_date, default the workspace's
snoozedqueryinclude (default) or exclude
curl "https://app.sayweek.com/api/v1/todos" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"
POST/todos/{key}/snoozewrite

Snooze a to-do (approves or completes nothing)

Parameters
keypathrequiredThe to-do's key, e.g. approve:2026-W47 (the colon may be percent-encoded)
Idempotency-KeyheaderReplays the first response for 24 h (same key + same request).
curl -X POST "https://app.sayweek.com/api/v1/todos/{key}/snooze" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body
{}
DELETE/todos/{key}/snoozewrite

Un-snooze a to-do

Parameters
keypathrequired
curl -X DELETE "https://app.sayweek.com/api/v1/todos/{key}/snooze" \
  -H "Authorization: Bearer $SAYWEEK_TOKEN"

Try it

Call the API right here with your own account – no key to copy. The console gets a 1-hour token for the workspace you’re signed in to; it never gets the approve scope.

Webhooks

Sayweek POSTs a signed JSON event to your HTTPS endpoint when something happens. Add endpoints in Settings → Integrations → Webhooks, or subscribe from code with POST /webhooks.

Events

post.createdPost createdA new draft or idea in a slot
approval.requestedApproval requestedA draft is ready for approval
post.approvedPost approvedSomeone approved a post
post.scheduledPost scheduledThe post is booked on the network
post.publishedPost publishedThe post went out
post.failedPublishing failedThe post didn't go out
idea.createdNew ideaAn idea landed in the ideas box
comment.receivedNew commentSomeone commented on a published post
review.commentClient feedbackA note on an approval link
todos.changedTo-dos changedA person's Sayweek to-dos changed (API / OAuth subscriptions only, about their own user)

Payload

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…"
  }
}

Verifying the signature

Each delivery has a Sayweek-Signature header: t=<unix seconds>,v1=<hex HMAC-SHA256 of “t.raw body” with your secret>. Compare in constant time and reject timestamps older than 5 minutes – that blocks replays.

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));
}

Retries, log and auto-off

  • Any 2xx within 8 seconds counts as delivered. Timeouts, network errors, 408, 409, 425, 429 and 5xx are retried with exponential back-off (up to 8 attempts over about 30 hours); other 4xx answers are final. The event id stays the same, so you can de-duplicate.
  • Every attempt is in the delivery log (Settings → Webhooks → Delivery log) with the status, time and the first lines of your answer – and can be sent again with one click.
  • An endpoint that keeps failing for a day is switched off automatically, and the workspace owners get a notification. Fix it, then switch it back on.
  • Only public https:// addresses are accepted – private, loopback and link-local IPs are blocked, checked when you save and again on every delivery. Redirects aren’t followed.

Claude & ChatGPT

Sayweek is a remote MCP server (Streamable HTTP, OAuth 2.1) – add it to Claude or ChatGPT with this URL:

MCP
https://app.sayweek.com/api/mcp
  • claude.ai: Settings → Connectors → “Add custom connector” → paste the URL → Connect → sign in → Allow.
  • ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode → Create → the URL, Authentication: OAuth.

Claude Code:

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

Rate limits

Limits are per token and minute. Over the limit you get 429 with a Retry-After header (seconds).

120 / minute

Reads (GET)

30 / minute

Writes (POST, PATCH, DELETE)

6 / minute

Generations (POST /generate)

Safe retries: on POST, an Idempotency-Key header replays the first response for 24 hours. Lists are paged: { data, next_cursor } – ask for the next page with ?cursor=.

Errors

Errors always look the same; code is stable, message is for humans.

JSON
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the \"write\" scope.",
    "details": {
      "required": "write",
      "granted": [
        "read"
      ]
    }
  }
}
401unauthorizedMissing, unknown, expired or revoked token.
403insufficient_scopeThe token lacks the scope (details.required).
403plan_requiredThe workspace’s plan doesn’t include this.
403approvals_disabledApproving through the API is switched off in the workspace.
404not_foundNo such object in this workspace.
400invalid_requestA parameter or the body is invalid (details say which).
409conflictThe object changed or is in a state that doesn’t allow this.
422idempotency_mismatchThe Idempotency-Key was used with a different request.
429rate_limitedToo many requests – wait Retry-After seconds.
500internalOur fault. Retry later; we’ve been notified.

SDKs & tools

Ready-made building blocks – all generated from the same OpenAPI description.

Changelog

  1. Webhooks with signed, retried deliveries and a delivery log; /webhooks and /me endpoints; OAuth apps with branded consent; the try-it console; Postman collection, n8n node, JS and Python clients.

  2. API v1: brands, channels, posts, ideas, week, generate, calendar, analytics; MCP server for Claude and ChatGPT; OAuth 2.1 with PKCE.

Developers: API and MCP (Claude, ChatGPT) – Sayweek