Build on ReputeCast

Explanation

For:: Developers

Every ReputeCast instance serves a newsletter REST API under /api/v1 at its own public URL, described by an OpenAPI 3.1 document that the server generates from its code. People, API keys and MCP agents all pass the same permission check, so a key can do what its permissions allow and nothing more. Errors are RFC 9457 problem documents with a stable code.

How a request works

Your code calls https://<public URL>/api/v1/… with the header Authorization: Bearer <key>. Operations on a workspace take its slug in the path, for example /api/v1/workspaces/acme-newsletter/campaigns.
ReputeCast looks the key up by its hash, refuses it with 401 when it is unknown, revoked or expired, and limits its permissions to what the member who created it holds at that moment.
The operation’s permission (x-permission in the OpenAPI document) is checked. When it is missing, the answer is 403 with the permission key and up to two members who hold it.
The answer is JSON (application/json), or a problem document (application/problem+json) when the call fails. Answers carry X-RateLimit-* headers (see rate limits).

Make your first API call walks through these steps with curl, and authentication and API keys describes the keys in detail.

Get the OpenAPI document

Your instance publishes its OpenAPI document without authentication, in four forms:

Path	Format
`/api/openapi.json`	OpenAPI 3.1, JSON
`/api/openapi.yaml`	OpenAPI 3.1, YAML
`/api/openapi-3.0.json`	OpenAPI 3.0, JSON
`/api/openapi-3.0.yaml`	OpenAPI 3.0, YAML

The reputecast openapi command prints the same document without a database or a config file (--yaml for YAML), so you can generate it in CI from the release you run:

curl -o reputecast-openapi.json https://reputecast.example.com/api/openapi.json
reputecast openapi --yaml > reputecast-openapi.yaml

What to know about the document:

It describes every operation of the server, including the ones only the web app calls with a signed-in session (sign-in, account security, Instance admin). The API reference on this site lists only the operations an API key can call.
Each operation has an operationId (such as list-campaigns), one tag, and three extensions: x-access (who may call it: workspace, key, user, instance_admin or public), x-permission (the permission key it needs) and, on the operations only integrations call, x-integration.
It has no servers entry: give your client your instance’s public URL as the base URL.
The instance serves the document but no reference pages. Use the API reference here.

Generate a client

Any OpenAPI generator can read the 3.1 document. Use the 3.0 variants with generators that read only OpenAPI 3.0. The ReputeCast web app builds its own TypeScript types with openapi-typescript (Checked October 2026), which reads the document from a URL:

npx openapi-typescript https://reputecast.example.com/api/openapi.json -o reputecast.d.ts

Most generators name methods after the operationId, so list-campaigns becomes a listCampaigns method or similar.

Call the API from your server

API keys are secrets, so call the API from your backend, a scheduled job or a workflow tool, never from a web page. The /api/ paths send no CORS headers, and the server refuses cross-site browser requests that change data. To collect signups on a website, embed a signup form instead: its endpoints accept requests from the sites you allow.

What you can build

Send transactional email with the APIPassword resets, receipts and alerts from your product, with idempotency keys.

Receive webhooksSigned events for contacts, campaigns, email delivery and more.

Connect AI agents with MCPAn MCP server at /mcp with its own agent tokens and permissions.

Build an integrationIntegration keys, REST hooks and actions that keep consent.

Record events and conversionsStart automations from your product and attribute revenue to campaigns.

Provider adaptersConnect an email service that has no built-in adapter.

If you want to connect a tool without writing code, Zapier, Make, n8n and WordPress have ready-made integrations.

Defaults and limits

Setting	Default	How to change
Largest JSON request body	1 MiB	Fixed; larger for transactional send (48 MiB) and batch (64 MiB)
Largest uploads	Contact import 100 MiB, suppression CSV 16 MiB	Fixed
Addresses per add-suppressions call	1–1,000	Fixed
Campaigns per page	25	`pageSize`, 1–100
Contacts and suppressions per page	10	`pageSize`, 1–100
Audit log entries per request	50	`limit`, 1–200, with `cursor`

Request rates have their own page: rate limits. How each list operation pages its results is in pagination.

When to change them

These limits are fixed. Page through long lists with each operation’s paging parameters, use the batch operations for bulk work, and send files through the upload operations instead of a JSON body. Server operators can change the number of requests per minute a key may make with http.rate_limit_api (see the configuration reference).