> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# Guides

Each recipe is a copy-pasteable sequence for one task. Set `SATURATION_TOKEN` and swap in your own ids.

- [Apply a rate pack](#apply-a-rate-pack)
- [Add an incentive](#add-an-incentive)
- [Subscribe to webhooks](#subscribe-to-webhooks)

## Apply a rate pack

List an available pack, then enable it for the workspace. Every project in the workspace can use enabled rate packs.

```bash
# 1. List the rate packs available in the workspace
curl "https://next-api.saturation.io/v1/library/rate-packs" \
  -H "Authorization: Bearer $SATURATION_TOKEN"

# 2. Enable a pack at the workspace
curl -X POST "https://next-api.saturation.io/v1/library/rate-packs/pack_iatse/enablement" \
  -H "Authorization: Bearer $SATURATION_TOKEN"

```

To remove it from every project, call `DELETE /library/rate-packs/{packId}/enablement`.

## Add an incentive

Enable an incentive pack for the workspace, then add one of its programs to a production. Repeating the add request is safe.

```bash
# 1. Enable the incentive pack at the workspace
curl -X POST "https://next-api.saturation.io/v1/library/incentive-packs/pack_us_state/enablement" \
  -H "Authorization: Bearer $SATURATION_TOKEN"

# 2. Inspect the pack's programs
curl "https://next-api.saturation.io/v1/library/incentive-packs/pack_us_state/programs" \
  -H "Authorization: Bearer $SATURATION_TOKEN"

# 3. Add a program to the production
curl -X POST "https://next-api.saturation.io/v1/projects/prj_a1/library/incentives" \
  -H "Authorization: Bearer $SATURATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "programId": "ipr_ga_30" }'
```

Use `expand=source` to include the original Saturation program:

```bash
curl "https://next-api.saturation.io/v1/projects/prj_a1/library/incentives?expand=source" \
  -H "Authorization: Bearer $SATURATION_TOKEN"
```

Editing the production's copy does not change where it came from. See [Concepts](/concepts.md).

## Subscribe to webhooks

Register an HTTPS endpoint and pick the events you want, and Saturation calls you when something changes. The `url` must be HTTPS. Unsafe URLs are blocked at registration.

```bash
curl -X POST "https://next-api.saturation.io/v1/webhooks" \
  -H "Authorization: Bearer $SATURATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/saturation",
    "events": ["transaction.created", "budget.changed"],
    "secret": "whsec_your_signing_secret"
  }'
```

`POST /webhooks/{id}/test-delivery` sends a test delivery. `GET /webhooks/{id}/deliveries` lists recent attempts.

A subscription belongs to the account that created it and receives only events that account can read. If the account loses access, the subscription stops. For delivery headers, signature verification, and the full event list, see [Webhook Events](/webhook-events.md).

## Next

- [Pagination](/pagination.md): read every row past the first page with `nextCursor`.
- [Idempotency](/idempotency.md): send an `Idempotency-Key` to retry a create safely.
- [Errors](/errors.md): error responses, status codes, and retries.