# API reference

> Complete reference for the Caramel Public API — 19 tools across 7 categories, with rate limits, errors, tier gates, and versioning.

The Caramel Public API exposes 19 tools across 7 categories. Every tool is available over the [MCP protocol](../get-started/authentication) and, when the REST gateway ships, over plain HTTP.

Start with [`caramel.v1.meta.capabilities`](tools) to discover the live tool catalog at runtime — it includes per-tool tier requirements and is updated whenever new tools ship.

## In this section

- [Tools](tools) — the full tool catalog grouped by category, with tier and scope for each tool.
- [Rate limits](rate-limits) — per-token, per-IP, and per-host caps; response headers; backoff strategy.
- [Errors](errors) — every error code, the JSON shape, the retry matrix, and idempotency rules.
- [Tiers and scopes](tiers-and-scopes) — which tier and OAuth scope each capability requires; AI credit consumption.
- [Webhooks](webhooks) — outbound event delivery (coming soon) and the polling workarounds available today.
- [Changelog](changelog) — version history and the breaking-change policy.
- [Downloads](downloads) — OpenAPI specs (3.1 and 3.0), Postman collection, and the TypeScript SDK.

## Quick orientation

| If you want to… | Start here |
|---|---|
| Discover what's available | [`caramel.v1.meta.capabilities`](tools#meta) |
| Read your business ID | [`caramel.v1.business.list`](tools#business) |
| Generate a campaign with AI | [`generate_campaign`](tools#campaign) |
| Add a contact to your audience | [`caramel.v1.contact.upsert`](tools#audience) |
| Submit a form programmatically | [`caramel.v1.form.submit`](tools#forms) |
| Check your sender domain status | [`caramel.v1.domain.status`](tools#provisioning) |
| Browse pre-built campaign templates | [`list_template_library`](tools#templates) |

## Concepts

Before diving into individual tools, read [Concepts](../concepts/index) — it explains campaigns, journeys, broadcasts, segments, and how authentication works end to end.