Downloads

Machine-readable API specs, a Postman collection, and the TypeScript SDK.

OpenAPI specs

Two spec files are published. Both describe the same caramel.v1.* surface.

Format	File	Use
OpenAPI 3.1	openapi.yaml	Code generators, Speakeasy, Fern, Stainless, and any tool that supports 3.1
OpenAPI 3.0	openapi-3.0.yaml	Postman import, older generators, tools that don’t yet support 3.1

Download them from the public API docs package or directly from the repository at docs/public-api/openapi.yaml and docs/public-api/openapi-3.0.yaml.

Both files are regenerated on every release. Check the info.version field to confirm you have the current version.

Note The REST gateway (gateway.caramelme.com) is not yet deployed. The specs describe the intended REST surface. Until the gateway ships, use the MCP endpoint (app.caramelme.com/api/functions/caramel-mcp) for all tool calls. See Authentication.

Postman collection

Import openapi-3.0.yaml directly into Postman using Import → OpenAPI. Postman will generate a collection with one request per tool.

After importing:

1. Create a Postman environment with TOKEN set to your OAuth bearer token and BUSINESS_ID set to your business ID.
2. Every request uses {{TOKEN}} in the Authorization: Bearer header.
3. Run list_businesses first to confirm your token is valid, then copy the returned id into {{BUSINESS_ID}}.

Tip The caramel.v1.meta.capabilities request needs no variables and is a useful first call to confirm connectivity.

TypeScript SDK

The @caramel/sdk package is the recommended client for TypeScript and JavaScript projects. It wraps the MCP tool calls with typed methods, handles token refresh automatically, and normalizes error responses (including the upstream messsage typo — see Errors).

Install

npm install @caramel/sdk

Quick start

import { CaramelSDK } from '@caramel/sdk';

const sdk = new CaramelSDK({ accessToken: process.env.CARAMEL_TOKEN });

const businesses = await sdk.businesses.list();
const businessId = businesses[0].id;

const draft = await sdk.campaigns.generate({
  businessId,
  prompt: 'Welcome new customers with a 3-email journey',
  campaignType: 'journey',
});

await sdk.campaigns.deploy(draft.id);

Modules

Module	Tools wrapped
sdk.businesses	list_businesses
sdk.campaigns	All 9 campaign tools
sdk.templates	list_template_library, deploy_template, caramel.v1.template.list
sdk.flows	WhatsApp Flow generation (Growth tier)

Error handling

The SDK throws CaramelError on all API failures. Import CaramelErrorCode for typed error matching:

import { CaramelError, CaramelErrorCode } from '@caramel/sdk';

try {
  await sdk.campaigns.generate({ businessId, prompt });
} catch (err) {
  if (err instanceof CaramelError) {
    if (err.code === CaramelErrorCode.INSUFFICIENT_CREDITS) {
      // Prompt user to add credits
    }
  }
}

Full error code reference is in Errors.

Build from source

cd packages/caramel-sdk
npm run build      # ESM + CJS + TypeScript declarations → dist/
npm run typecheck  # Zero-error tsc check
npm test           # 43 unit tests via vitest

Output files:

File	Format
dist/index.js	ESM — for bundlers and Node ≥ 18
dist/index.cjs	CJS — for require()
dist/index.d.ts	TypeScript declarations

The SDK has no runtime dependencies and uses native fetch.

Next steps

• Tools — full tool catalog and parameter reference.
• Authentication — get an OAuth token before making calls.
• Errors — the complete error catalog.