Migrate from v3 with an AI agent

This page is a ready-made skill for AI coding assistants (Claude Code, Cursor, and similar agents) that migrate an integration from the v3 API to the latest header-based API.

Save it as a skill file in your project — for example .claude/skills/api-v3-to-latest-migration/SKILL.md, or as a Cursor project rule such as .cursor/rules/api-v3-to-latest-migration.mdc — or paste the instructions below into the agent's context at the start of a migration task.

The agent must always work from the migration guide, which is the authoritative source. The Markdown source, meant for agents, is at migrate-from-v3-to-v2026-03-15.md, and the full documentation index is at llms.txt.

"Latest" means whatever the guide at that URL currently documents. This page is not the source of endpoint truth: the agent must re-fetch the guide on every run rather than relying on anything memorized or restated here.

Skill file

---
name: api-v3-to-latest-migration
description: |
  Migrate an integration from the Omnisend public API v3 to the latest header-based API (`/api/` base path plus `Omnisend-Version` header). Discovers current v3 usage, maps endpoints and fields against the published migration guide, flags removed or changed behavior, and plans a narrow, verifiable code change.
  Triggers: "migrate from v3", "move off the v3 API", "upgrade to the latest Omnisend API", "v3 to v2026-03-15", "is this endpoint still supported in the new API", "API sunset".
---

# Migrate from Omnisend API v3 to the latest API

The published migration guide is the single source of truth. Never answer from memory — the target version, endpoint mapping, and behavior changes evolve.

- Guide: https://api-docs.omnisend.com/docs/migrate-from-v3-to-v2026-03-15
- Markdown for agents: https://api-docs.omnisend.com/docs/migrate-from-v3-to-v2026-03-15.md
- Docs index: https://api-docs.omnisend.com/llms.txt

## 1. Read the guide first

```shell
curl -sSL https://api-docs.omnisend.com/docs/migrate-from-v3-to-v2026-03-15.md \
  -o /tmp/omnisend-migration-guide.md
```

Read the whole file before making any recommendation or code change. If the downloaded file starts with `<!DOCTYPE html>`, the Markdown fetch failed and you have the rendered page instead — stop. If it cannot be fetched at all, stop and say so — do not migrate from assumptions.

Two invariants the guide establishes; confirm everything else against it:

- The base path moves from `/v3/` to `/api/`.
- Every request carries `Omnisend-Version: <target-version>` alongside the auth header. Take the exact version string and auth header format from the guide; do not invent or extrapolate future version identifiers.

## 2. Discover current v3 usage

```shell
rg -n 'api\.omnisend\.com|/v3/|X-API-KEY|X-Rate-Limit' -g '!vendor' -g '!node_modules'
```

Inventory: base URLs, every endpoint called, auth header construction, pagination loops, error handling and status-code branching, retry and rate-limit logic, and response models, DTOs, and fixtures. Include tests and mocks — they usually encode the v3 contract too.

## 3. Map each usage against the guide

For every inventoried call, record from the guide:

- the new path and HTTP method, including method semantics changes such as `PUT` becoming `PATCH`
- request and response field renames, plus new required fields
- the pagination model for that resource — it differs per resource
- the error format and status-code changes
- the rate limits that apply to that endpoint

If a resource, endpoint, or field has no documented replacement, do not assume parity. Record it as an open item and report it.

## 4. Plan the change

Write a short plan before editing: what changes once in the client or transport layer (base path, auth and version headers, error parsing, retry and backoff), what changes per call site, and which data models, fixtures, and tests must follow. Centralize the base path, headers, and error decoding in one place instead of touching every call site.

Call out data-model impacts explicitly — renamed identifiers, changed units or types, asynchronous acceptance, and upsert-versus-create status codes are behavior changes, not string replacements.

## 5. Implement narrowly

- Change only what the migration requires; no unrelated refactors or reformatting.
- Match the repository's existing style and client abstractions.
- Keep the version string in configuration rather than scattering literals.
- Update tests and fixtures alongside the code so the new contract is asserted.

## 6. Verify

- Run the repository's own build, lint, and test commands and get them green.
- Re-read the guide sections for every endpoint touched and confirm the diff matches.
- For live calls, use a test brand and an API key from the environment. Do not make live customer-affecting calls — writes, sends, or deletes on production brands — without explicit approval.
- Prefer read-only `GET` probes or dry-run validation first.

## Safety

- Never print, log, or commit API keys or tokens. Reference them as environment variables and redact them from any pasted output.
- Never assume undocumented parity. Report unsupported or changed endpoints instead of inventing a mapping.
- Do not hard-code speculative future version behavior; the guide is authoritative and may change.

## Report

Finish with: endpoints migrated (v3 path to new path), behavior changes handled, unsupported or open items needing a product decision, and the verification commands run with their results.