Brand Data API Overview

Read your brand's conversations, messages, and contacts, and configure your integration providers and event definitions, over a simple HTTP API.

The Brand Data API lets you work with your LiveRecover data and your integration configuration over HTTP.

It does two things. It flows data out — the conversations LiveRecover has had with your customers, the messages within them, and the contacts those conversations belong to — so you can mirror it into your own systems, build reporting, or reconcile recovery activity against your store. And it lets you configure the integration that flows data in: the providers you send events from, and the event definitions that describe those events.

Where the Custom Integration webhooks carry your events into LiveRecover, this API is how you set those webhooks up and read the results back.

At a glance

Base URL — your account contact will give you the exact host for your environment. Every path below is relative to it.
Authentication — a Bearer token: your Brand Data API key. See Authentication.
Format — JSON request and response bodies. All timestamps are ISO-8601 strings (UTC). All ids are UUIDs.
Brand-scoped — your key only ever sees your own brand's data. There is no cross-brand access, and ids belonging to another brand are reported as 404 Not Found.
Callable from a browser — the API answers the browser's CORS preflight (OPTIONS) with 204 and no authentication, so requests from a web page work without a proxy in front. Treat this as a convenience for internal tools and prototypes: never ship your API key in client-side code, since anyone who loads the page can read it, and the key grants full access to your brand's data. For anything customer-facing, call the API from your server.

Endpoints

Reading your data

Method	Path	Description
`GET`	`/health`	Public liveness probe. No authentication.
`GET`	`/conversations`	List your brand's conversations (paginated).
`GET`	`/conversations/{id}`	Fetch a single conversation by id.
`GET`	`/conversations/{id}/messages`	List the messages in a conversation (paginated).
`GET`	`/contacts`	List your brand's contacts (paginated).
`GET`	`/contacts/{id}`	Fetch a single contact by id.

Configuring your integration

Method	Path	Description
`GET`	`/providers`	List your providers.
`POST`	`/providers`	Create a provider and mint its credentials.
`GET`	`/providers/{providerId}`	Fetch one provider.
`PATCH`	`/providers/{providerId}`	Update a provider's name, settings, or state.
`GET`	`/providers/{providerId}/event-definitions`	List a provider's event definitions.
`POST`	`/providers/{providerId}/event-definitions`	Create an event definition.
`GET`	`/providers/{providerId}/event-definitions/{definitionId}`	Fetch one event definition.
`PATCH`	`/providers/{providerId}/event-definitions/{definitionId}`	Update an event definition.

Managing your keys

Key management is authenticated by a dashboard session, not by an API key — an API key can never mint another API key. See Authentication.

Method	Path	Description
`POST`	`/keys`	Mint a Brand Data API key. Shown once.
`GET`	`/keys`	List your keys (metadata only — `id` and display prefix).
`DELETE`	`/keys/{keyId}`	Revoke a key immediately. Use the `id` from the list — not the display prefix.

Health check

GET /health is the one public endpoint — it requires no Authorization header and never touches your data. Use it to confirm reachability and as a load-balancer/uptime probe.

curl -sS https://<your-vyg-api-host>/health

{ "status": "ok" }

Start here

Authentication — how to obtain and present your API key.
Managing your integration — configure a provider and its event definitions end to end.
Pagination — the cursor/limit model shared by every list endpoint.
Providers — read, create, and update providers.
Event definitions — describe the events you send.
Conversations — list and fetch conversations.
Messages — list the messages within a conversation.
Contacts — list and fetch contacts.
Errors — the status codes you can expect and what they mean.