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.
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.
Replays 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
}
Update text or schedule of a not-yet-approved post
Parameters
id
pathrequired
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`)
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
id
pathrequired
Idempotency-Key
header
Replays 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"
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.
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
id
pathrequired
Idempotency-Key
header
Replays the first response for 24 h (same key + same request).
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.
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).
Replays 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": []
}
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-Key
header
Replays the first response for 24 h (same key + same request).
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.
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.
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
tz
query
IANA time zone for due_date, default the workspace's
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.created
Post created
A new draft or idea in a slot
approval.requested
Approval requested
A draft is ready for approval
post.approved
Post approved
Someone approved a post
post.scheduled
Post scheduled
The post is booked on the network
post.published
Post published
The post went out
post.failed
Publishing failed
The post didn't go out
idea.created
New idea
An idea landed in the ideas box
comment.received
New comment
Someone commented on a published post
review.comment
Client feedback
A note on an approval link
todos.changed
To-dos changed
A person's Sayweek to-dos changed (API / OAuth subscriptions only, about their own user)
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.
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"
]
}
}
}
401
unauthorized
Missing, unknown, expired or revoked token.
403
insufficient_scope
The token lacks the scope (details.required).
403
plan_required
The workspace’s plan doesn’t include this.
403
approvals_disabled
Approving through the API is switched off in the workspace.
404
not_found
No such object in this workspace.
400
invalid_request
A parameter or the body is invalid (details say which).
409
conflict
The object changed or is in a state that doesn’t allow this.
422
idempotency_mismatch
The Idempotency-Key was used with a different request.
429
rate_limited
Too many requests – wait Retry-After seconds.
500
internal
Our fault. Retry later; we’ve been notified.
SDKs & tools
Ready-made building blocks – all generated from the same OpenAPI description.
OpenAPI 3.1
Import into any client generator, Insomnia or Bruno.
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.
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