Migration guide

Update existing integrations for the September 2026 API changes: new URLs, renamed routes and tools, a new collection error format, one list format and snake_case field names. Find each replacement below. See the changelog for dates and details.

Hosts

The retired MCP hosts no longer resolve. Paths on api.vyg.app/v1 are listed in the REST API reference.

Credentials

• vyg_ and vyg_ba_ API keys keep working on api.vyg.app with the scopes they carry. See API keys.
• vyg_live_ keys are not accepted. Requests get 401 with legacy_credential_not_supported. Create a vyg_ba_ key instead.
• MCP sign-ins made against mcp.vyg.app or cdp-mcp.vyg.app do not carry over. Sign in again against https://api.vyg.app/mcp.
• Scope names: cdp:read is not a scope. Use the granular read scopes, such as customers:read, commerce:read and insights:read. See Scopes.

MCP server name

The setup guides now name the server vyg. If you added it as liverecover or cdp-mcp, remove those entries and add it again:

claude mcp remove liverecover
claude mcp remove cdp-mcp
claude mcp add --transport http vyg https://api.vyg.app/mcp

Tool names

Tools were renamed on 2026-09-26 to a verb_noun pattern, and campaign tools use "campaign" instead of "workflow". Until 2026-09-27 the old names were still accepted; they are now removed. Calling an old name fails, so update saved prompts, scripts and per-tool approvals or allowlists (for example Claude Code's mcp__vyg__<tool> permissions) to the current names.

query_shopify and query_klaviyo are no longer listed. Use read_shopify and mutate_shopify, and read_klaviyo and write_klaviyo, which take the same arguments.

get_customer_segments was the 2026-09-26 name of the RFM tool. It is get_rfm_tiers and is separate from saved segments.

Routes, tools and scopes renamed on 2026-09-27

Campaign reads moved from /v1/workflows to /v1/campaigns, performance stats and campaign comparison became GET requests, and every parameter these routes and tools take is snake_case. There are no aliases: the old paths answer 404, and an old argument or query parameter name is refused rather than ignored (400 bad_request over REST, an invalid-arguments error from the MCP tool).

REST routes

stats and campaign_ids are lists. Send them as repeated parameters (stats=conversations&stats=aov) or as one comma-separated value (stats=conversations,aov). The OpenAPI operation ids changed with the routes: campaigns.list, campaigns.get, campaigns.compare, stats.get, conversations.search and customers.fields.

Tool arguments

Response fields did not change in this rename. They became snake_case on 2026-09-28; see Envelopes and field names changed on 2026-09-28.

Scopes

Sign-ins made before the rename keep their access: a token that carries workflows:read or dashboard:read is read as campaigns:read or stats:read, and refreshing it returns the new names. New sign-ins should ask for the new names; the old ones are no longer advertised. New VYG API keys can also carry these scopes. See API keys and Scopes.

Collect error envelope on 2026-09-28

Errors from the collect endpoints on https://cdp.vyg.app (POST /cdp/events and POST /cdp/ingest) now use the REST API format, {"error": {"code", "message"}}, instead of the flat {"error": "<code>", "error_description": "..."}. Read the code from error.code and the text from error.message. Success responses are unchanged. Error responses with the envelope also carry an X-Request-Id header. Some responses (unserved methods or paths, rate limits and temporary failures) use a {"message": "..."} body, so check the status and read error.code only when the body has an error object.

A 503 that carries failed is the old service_unavailable_partial: resend only the events at those indexes. See Collect errors.

Envelopes and field names changed on 2026-09-28

Every list now returns the same envelope, every single record is returned bare, offset paging is replaced by opaque cursors, and every request and response field is snake_case. This covers query parameters, path parameters, request bodies, MCP tool arguments, response keys and the list envelope itself. There are no aliases: an old query parameter, body field or tool argument is refused (400 bad_request over REST, an invalid-arguments error from the MCP tool), and responses carry only the new names. The error envelope, { "error": { "code", "message" } }, is unchanged.

List envelope

Every list returns { data, next_cursor }. next_cursor is null on the last page and always null on a list that returns everything in one page. See Pagination.

Customer search (GET /v1/customers/search) returns one page, so its next_cursor is always null. catalog_version is "fields-v1" when you ask for catalog=fields-v1, otherwise null. The dropped envelope keys (totalSize, pageSize, offset, scope, totalCount, totalFound and limit) have no replacement; count the rows you read if you need a total.

Offset paging replaced by cursors

The offset parameter is removed; sending it returns 400 bad_request. Pass the next_cursor of the previous page as cursor, and stop when it is null. Orders, subscriptions and customers at risk still stop at row 10,000: that page has next_cursor: null, and a cursor at or past row 10,000 returns 400.

Each endpoint keeps its other filters. Orders take created_at_gte, created_at_lte, state, billing_status, customer_email, customer_phone and customer_id; at-risk customers take as_of.

Single records are no longer wrapped

These operations returned { "data": { ... } } and now return the object itself:

Replace response.data.id with response.id for these. Other single reads, such as a customer, an order, a segment or a report, were already bare.

Request parameters

Tool arguments renamed on 2026-09-28

Field names

Timestamps and ids that appear on many resources change the same way everywhere:

The tables below list the other renamed fields by resource. A field that is not listed kept its name.

Conversations, messages and contacts

Conversation search results (GET /v1/conversations/search, search_conversations):

get_conversation_details (MCP only):

Providers and event definitions

The contents of settings, payload_schema and identifier_mappings are stored as you send them and are not renamed.

API keys

plaintext on a created or rotated key is unchanged.

Customers

Activity timeline (GET /v1/customers/{id}/timeline, get_customer_activity):

A customer's orders and subscriptions (GET /v1/customers/{id}/orders and /subscriptions, list_customer_orders, list_customer_subscriptions):

sourceSystem and productKey change as in the timeline table.

Segments

schemaVersion on a segment is schema_version. The segment definition is stored as you send it and its keys are not renamed. See Segment rules.

Commerce and insights

Orders, subscriptions and at-risk rows were already snake_case; only their envelope changed. On products, images[].altText is images[].alt_text, on the list and on GET /v1/commerce/products/{id}. The LTV, RFM and top-products reports are unchanged and keep scope.

Brand, stats and conversation insights

GET /v1/brand (get_brand):

isEnabled and lookupId on integrations[] are is_enabled and lookup_id.

GET /v1/stats (get_performance_stats) and GET /v1/campaigns/compare (compare_campaigns):

get_performance_stats also returns query: the stats, campaign_id and timezone the numbers were computed with. timezone is America/Los_Angeles when the request named none.

Conversation insights (list_conversation_insights, list_insight_conversations):

conversationId, checkoutState and updatedAt change as in the tables above.

Campaigns

GET /v1/campaigns, GET /v1/campaigns/{campaign_id} and GET /v1/campaigns/compare (list_campaigns, get_campaign, compare_campaigns):

compare_campaigns returns the compared campaigns under campaigns (was workflows). supportEmail inside agent_reply is support_email. The contents of goal, flow_messages[].cart.rules and filters[].filter.rule are not renamed. Message variants, discounts, campaign writes and campaign building options were already snake_case.

Klaviyo documentation search

search_klaviyo_docs (MCP only):

The payloads that read_shopify, mutate_shopify, read_klaviyo and write_klaviyo (and the unlisted query_shopify and query_klaviyo) return come from Shopify and Klaviyo and are not renamed.

Documentation URLs

The documentation moved from /docs, /cdp-api and /mcp to root-level sections on docs.vyg.ai. Old URLs, including those on docs.cdp.vyg.app and docs.mcp.vyg.app, redirect to the new pages.