CatCaster Public API (v1)

Base URL

All resource routes live under https://www.catcaster.com/api/v1. This is a marketing overview; machine-readable details are in OpenAPI.

Authentication

• API keys: Authorization: Bearer sk_live_… (create in Settings → Developer)
• OAuth: Supabase access tokens with catcaster.* scopes (MCP and ecosystem OAuth)

Core resources

• GET /api/v1/projects — list workspaces (projects)
• GET /api/v1/posts, drafts, schedule, publish — post lifecycle
• GET /api/v1/jobs/:id — async jobs (e.g. image generation)
• POST /api/v1/tools/:toolName/execute — frozen tool names and catcaster_* aliases
• /api/v1/webhooks — outbound subscriptions (see /webhooks)

Errors & safety

Responses use a normalized error envelope with error.code, error.message, and error.requestId (X-CatCaster-Request-Id). Destructive actions may return 409 CONFIRMATION_REQUIRED — retry with confirmationId. Use Idempotency-Key on draft, schedule, and publish mutations.

SDK & MCP

TypeScript client: packages/sdk in the GitHub repo. Prefer MCP when your host supports remote tools and OAuth instead of raw REST.

Not the same as inbound channel webhooks

Social networks (Meta, X, etc.) send inbound events to CatCaster under /api/webhooks/… for publishing infrastructure. Integrators building automations should use this public v1 API and outbound developer webhooks — not those internal routes.