# Changelog

> Version history for the Caramel Public API, plus the versioning and breaking-change policy.

All notable changes to the Caramel Public API. Dates are UTC. See [Versioning policy](#versioning-policy) for the compatibility guarantee.

## v1.0.0 — 2026-06-05

Initial public release of the `caramel.v1.*` tool catalog.

### Added

**19 tools across 7 categories:**

- **meta** — `caramel.v1.meta.capabilities`, `caramel.v1.meta.usage`
- **business** — `list_businesses` (`caramel.v1.business.list`)
- **audience** — `caramel.v1.contact.upsert`
- **forms** — `caramel.v1.form.list`, `caramel.v1.form.submit`
- **campaign** — `generate_campaign`, `refine_campaign`, `deploy_campaign`, `pause_campaign`, `resume_campaign`, `get_campaign`, `get_campaign_suggestions`, `list_campaigns`, `delete_campaign`
- **templates** — `caramel.v1.template.list`, `list_template_library`, `deploy_template`
- **provisioning** — `caramel.v1.domain.status`

**Versioned namespace:** `caramel.v1.<category>.<action>` convention established. All 12 legacy tool names (e.g. `list_businesses`, `generate_campaign`) continue to work as aliases and dispatch to the same handlers — no migration required.

**OAuth scopes introduced:** `meta:read`, `forms:read`, `forms:write`, `audience:write`, `provisioning:write`.

### Deferred

- **send category** (`caramel.v1.email.send`, `caramel.v1.sms.send`, `caramel.v1.whatsapp.send`, `caramel.v1.push.send`) — pending per-tenant sender credential infrastructure. Will require `messaging:send` scope when live.
- **Outbound webhooks** — infrastructure designed; delivery to builder URLs not yet enabled. See [Webhooks](webhooks).
- **`audience:read` scope** — `caramel.v1.contact.list` planned for a future release.

### Removed

Nothing — this is the first published version.

---

## Versioning policy

The Caramel Public API follows a namespace-based versioning model.

**`caramel.v1.*` is the current stable namespace.** It will remain backward compatible for the lifetime of v1 — adding new tools, parameters, or response fields is never a breaking change.

**Breaking changes** (removing a tool, removing a required parameter, changing an existing response shape) will not happen within a namespace. When a breaking change is necessary, a new namespace (`caramel.v2.*`) ships alongside v1, and v1 is maintained for at least 12 months with a migration guide.

**Aliases** (legacy names like `list_businesses`) are part of v1 and will not be removed without a major version bump.

**What is not a breaking change:**

- Adding a new tool to the catalog
- Adding an optional parameter to an existing tool
- Adding new fields to a response object
- Adding new event types to the webhook catalog
- Adding new error codes not previously returned by a tool
- Changing the wording of `message` strings in error responses

**What is a breaking change:**

- Removing a tool or a required parameter
- Removing a field from a response that was previously documented
- Changing the type of an existing field
- Changing a documented status code for a given error condition

**How we notify you:**

Breaking changes ship in a new major namespace (`caramel.v2.*`) with at least 90 days' notice. The [changelog](#) (this page) is updated on every release. Subscribe to the API changelog via `caramel.v1.meta.capabilities` — the response includes a `changelog_url` field you can poll.

## Next steps

- [Downloads](downloads) — OpenAPI specs and SDK, both versioned.
- [Tools](tools) — full tool reference for the current v1 catalog.