@postwave/openapi

OpenAPI 3.1 spec for the Postwave API. MIT licensed as Layer 2 of the Postwave open-core architecture.

The authoritative source is openapi.yaml. A JSON twin lives at openapi.json for tooling that does not parse YAML.

What's covered

Every public route across the gateway and the four backend services:

• Migrations (Mailchimp / ConvertKit / Substack / Beehiiv / MailerLite / CSV)
• Subscribers, Campaigns, Sequences, Templates, Voice Profile
• Embeddable Forms (admin) and public Submissions
• Inbox Reality (per-campaign placement reports), Reputation, Auth Checks
• Sending (Postmark provisioning / warmup), Automations, Webhooks, Account

The full webhook event catalog (subscriber.created, migration.completed, form.confirmed, ...) is documented under webhooks: with payload schemas plus signature verification details.

Viewing the spec

Scalar (recommended)

Open viewer.html in a browser — it loads @scalar/api-reference-react from the CDN and renders the YAML in place.

# from this directory
python3 -m http.server 8000
# then open http://localhost:8000/viewer.html

Stoplight Studio / Redoc / Swagger UI

Point any OpenAPI 3.1 viewer at openapi.yaml.

npx @redocly/cli preview-docs openapi.yaml

Regenerating SDKs

The TypeScript and Python SDKs in this repo (packages/sdk-ts, packages/sdk-py) are hand-written, not generated, so they stay crisp and Postwave-shaped. When the spec changes:

1. Edit openapi.yaml (and mirror changes into openapi.json).
2. Update packages/sdk-ts/src/types.ts and the matching resource methods.
3. Update packages/sdk-py/postwave/types/*.py and resource methods.
4. Run the SDK test suites — they cover client wiring + webhook signatures.

Hosted docs

Production docs render at https://docs.postwave.app/api.