REST API reference

The REST API is served at:

https://api.vyg.app/v1

Each endpoint lists its inputs, responses and errors. Download the OpenAPI 3.1 specification at https://api.vyg.app/v1/openapi.json.

Conventions

Authentication: Authorization: Bearer <API key or sign-in token>. See Authentication.
Scopes: each operation names the scopes that allow it; any one is enough. See Scopes.
Sign-in only: operations marked "Requires sign-in (OAuth)" need an OAuth connection.
MCP tool: operations that are also an MCP tool name it, linked to the tool catalog.
Format: JSON bodies. Timestamps are ISO 8601 strings in UTC.
Account: see Account context to select your account and store.
Errors: {"error": {"code", "message"}}. See Errors.
Field names: every query parameter, path parameter, body field and response key is snake_case.
Lists: every list returns { data, next_cursor }; pass next_cursor back as cursor. See Pagination.
Single records: returned as the object itself, not wrapped in data.
Rate limits: a few operations are rate limited. See Rate limits.

Areas

Area	What it covers
Brand	Your business details and settings.
Conversations	Conversations and messages, conversation search, AI conversation insights, and contacts.
Customers	Customer list, lookup and profile, activity timeline, a customer's orders and subscriptions, customer fields.
Segments	Saved segments: rules, estimates, members and history.
Commerce	Store orders, subscriptions and products.
Insights	Lifetime value, RFM tiers, top products and customers at risk.
Campaigns	Campaigns, message variants, campaign building options and performance stats.
Discounts	Your saved discounts.
Integrations	Connected apps, event types, and custom integration providers and event definitions.
API keys	Create, list, rotate and revoke API keys.

Every campaign route is under /v1/campaigns: reads (GET /v1/campaigns, GET /v1/campaigns/{campaign_id}, GET /v1/campaigns/compare) and changes. Performance stats are GET /v1/stats. Both are on the Campaigns page. A campaign id from GET /v1/campaigns is the campaign_id every other campaign route and tool takes.

Customer segments and RFM

GET /v1/segments and the segment routes are saved segments: named rules you create. The RFM tiers from GET /v1/insights/rfm (the get_rfm_tiers tool) are based on order history. See Insights.

Concepts

Commerce data: store data, currencies and connection requirements.
Insights: how lifetime value, RFM tiers, top products and churn risk are computed.
Segment rules: the rule format for creating and changing segments.

Not in this reference

Event collection on https://cdp.vyg.app (/cdp/ingest, /cdp/events, /cdp/vyg.js). See Data collection.
Custom integration webhooks. See Custom Integration.
MCP-only tools such as get_conversation_details, read_shopify and read_klaviyo. See the tool catalog.