Sayweek for developers: API and MCP

Claude & ChatGPT (MCP)

Sayweek is a remote MCP server (Streamable HTTP, OAuth 2.1). Its URL:

https://app.sayweek.com/api/mcp

• claude.ai: Settings → Connectors → “Add custom connector” → paste the URL → Connect → sign in to Sayweek → Allow.
• ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode → Create → the URL, Authentication: OAuth.

Claude Code:

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

Tools for the assistant

• list_brands – brands and channels
• get_week_plan – the week's slots and posts
• get_calendar_context – where you'll be and what kind of day it is (from your calendar, no event titles)
• list_posts, list_ideas, get_analytics_summary – reading
• create_post_draft, update_post, add_idea – drafts and ideas
• generate_week_drafts, get_generation_job – Sayweek writes the week's drafts in the brand's voice
• approve_post – real scheduling – only with the “approve” scope and approvals turned on

Authentication

Every request: Authorization: Bearer <token>. The token is an API key (pp_…, Settings → Integrations → Claude & ChatGPT) or an OAuth access token (sw_at_…, valid for 1 hour, refreshable). Tokens are stored hashed only; a password reset revokes assistant connections.

OAuth 2.1: authorization code + PKCE (S256), dynamic client registration (RFC 7591), metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

Scopes

• read – brands, channels, plan, posts, ideas, calendar summary, analytics
• write – write/edit drafts, ideas, generate a week, delete unsent posts
• approve – approve = schedule for real; must also be allowed in the workspace, and every approval rule applies

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

Endpoints

Full reference (OpenAPI 3.1): https://app.sayweek.com/api/v1/openapi.json

Examples

curl

# Next week's plan
curl https://app.sayweek.com/api/v1/week?start=2026-10-05 \
  -H "Authorization: Bearer $SAYWEEK_KEY"

# A draft (never published by the API)
curl -X POST https://app.sayweek.com/api/v1/posts \
  -H "Authorization: Bearer $SAYWEEK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-2026-10-06-linkedin" \
  -d '{"channel_id":"<channel id>","date":"2026-10-06","text":"…","hashtags":["#sayweek"]}'

# Let Sayweek write next week (async job)
curl -X POST https://app.sayweek.com/api/v1/generate -H "Authorization: Bearer $SAYWEEK_KEY"
curl https://app.sayweek.com/api/v1/jobs/<job id> -H "Authorization: Bearer $SAYWEEK_KEY"

JavaScript

const api = (path, init = {}) =>
  fetch(`https://app.sayweek.com/api/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.SAYWEEK_KEY}`, "Content-Type": "application/json", ...init.headers },
  }).then(async (r) => {
    const body = await r.json();
    if (!r.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    return body;
  });

const { data: brands } = await api("/brands");
const job = await api("/generate", { method: "POST", body: JSON.stringify({ brand_ids: [brands[0].id] }) });
const status = await api(`/jobs/${job.id}`);
console.log(status.status, status.done, "/", status.total);

Errors, paging, limits

Error format: { "error": { "code", "message", "details" } }. Lists: { data, next_cursor } – next page: ?cursor=<next_cursor>. Limits per client and minute: 120 reads, 30 writes, 6 generations (429 + Retry-After). On POST, an Idempotency-Key header replays the first response for 24 hours.