API reference
The Caramel Public API exposes 19 tools across 7 categories. Every tool is available over the MCP protocol and, when the REST gateway ships, over plain HTTP.
Start with caramel.v1.meta.capabilities to discover the live tool catalog at runtime — it includes per-tool tier requirements and is updated whenever new tools ship.
In this section
Section titled “In this section”- Tools — the full tool catalog grouped by category, with tier and scope for each tool.
- Rate limits — per-token, per-IP, and per-host caps; response headers; backoff strategy.
- Errors — every error code, the JSON shape, the retry matrix, and idempotency rules.
- Tiers and scopes — which tier and OAuth scope each capability requires; AI credit consumption.
- Webhooks — outbound event delivery (coming soon) and the polling workarounds available today.
- Changelog — version history and the breaking-change policy.
- Downloads — OpenAPI specs (3.1 and 3.0), Postman collection, and the TypeScript SDK.
Quick orientation
Section titled “Quick orientation”| If you want to… | Start here |
|---|---|
| Discover what’s available | caramel.v1.meta.capabilities |
| Read your business ID | caramel.v1.business.list |
| Generate a campaign with AI | generate_campaign |
| Add a contact to your audience | caramel.v1.contact.upsert |
| Submit a form programmatically | caramel.v1.form.submit |
| Check your sender domain status | caramel.v1.domain.status |
| Browse pre-built campaign templates | list_template_library |
Concepts
Section titled “Concepts”Before diving into individual tools, read Concepts — it explains campaigns, journeys, broadcasts, segments, and how authentication works end to end.