# Downloads

> OpenAPI specs (3.1 and 3.0), Postman collection, and the TypeScript SDK for the Caramel Public API.

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](../get-started/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](errors#normalizing-error-bodies)).

### Install

```bash
npm install @caramel/sdk
```

### Quick start

```typescript
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:

```typescript
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](errors).

### Build from source

```bash
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](tools) — full tool catalog and parameter reference.
- [Authentication](../get-started/authentication) — get an OAuth token before making calls.
- [Errors](errors) — the complete error catalog.