Epinium API

Access: Settings → API Keys

Epinium exposes your data through a REST API so you can read it from your own tools: a custom dashboard, an analysis script or an AI assistant. It is the same information you see in the app, with the same figures.

In its current version the API is read-only: it is for querying, not for modifying campaigns or products.

Looking to use it from an AI assistant?

You do not need to write any code. The Epinium MCP connects this same data to Claude and other compatible assistants.

Generate a token

1. Go to Settings → API Keys
2. Click Create API key and give it a name that reminds you what it is for
3. Tick the permissions it needs
4. Copy the key and store it somewhere safe
5. Use it in the Authorization header of every request

The key is shown only once

The full value appears a single time when you create it. If you lose it there is no way to recover it: you have to revoke it and create another.

Permissions

Every token carries the permissions you tick when creating it. Grant only the ones your integration needs.

Permission	Gives access to
catalog:read	Products, brands, countries and clusters
campaigns:read	Campaigns, ad groups, targets, product ads and search terms
connections:read	Your account's Amazon connections
tasks:read	Epinium tasks and their items
skills:read	Epinium's catalog of validated marketing playbooks

A token reaches all the connections in your account. If you are an agency, it reaches the connections each client shared with you when accepting your invitation.

What endpoints it covers

Every resource has a list endpoint, and most also let you retrieve a single item by its id. The metrics resources only have a list: an aggregated row over a date range has no identifier of its own.

Catalog — catalog:read

Endpoint	What it returns
/v1/products	Your unified products
/v1/amazon-seller-products	The Seller Central view of each product
/v1/amazon-vendor-products	The Vendor Central view
/v1/amazon-advertising-products	The Advertising view
/v1/seller-product-metrics	Sales, sessions, Buy Box and rank per product
/v1/vendor-product-metrics	Vendor sales per product, with manufacturing and sourcing
/v1/product-brands	Your brands
/v1/countries	Countries and marketplaces
/v1/clusters	Your keyword segmentations

Advertising — campaigns:read

Endpoint	What it returns
/v1/campaigns	Your Amazon Advertising campaigns
/v1/campaign-metrics	Spend, sales, ACOS and ROAS per campaign
/v1/adgroups	The ad groups of each campaign
/v1/adgroup-metrics	Performance per ad group
/v1/targets	Keywords and product targets
/v1/target-metrics	Performance per target, with its keyword and match type
/v1/product-ads	The link between an ad group and the product it advertises
/v1/product-ad-metrics	Performance per advertised product, with its ASIN
/v1/search-terms	The actual shopper queries
/v1/search-term-metrics	Performance per query, with the text and the target that matched it

Connections, tasks and skills

Endpoint	Permission	What it returns
/v1/connections	connections:read	Your Amazon connections
/v1/tasks	tasks:read	Epinium tasks
/v1/task-items	tasks:read	The items of each task
/v1/skills	skills:read	Epinium's catalog of marketing playbooks

The skills catalog is content written by Epinium, not data from your account: it is the same for every client. Which parts of each playbook you receive depends on your plan.

There is also /v1/me, which tells you which permissions and which accounts your token reaches. It is the first useful call to check that the key works.

Three rules when reading the data

These three explain almost every question about interpreting the response:

• Monetary amounts are text, not numbers. "cost": "8.22" arrives as a string on purpose, so it does not lose precision when converted to a binary decimal.
• Ratios come as fractions, not percentages. An ACOS of 90.83% arrives as 0.908287. Multiply by 100 to display it.
• null is not 0. null means Amazon did not report that figure; 0 means an actual zero. An acos of null is a campaign that spent without selling, not free advertising. And new_to_brand_sales arrives as null on Sponsored Products because Amazon does not measure it for that format.

Limits

• Metrics require a date range. start_date and end_date are mandatory on every metrics resource.
• The range has a maximum, and it depends on the granularity. With granularity=total, 366 days; with granularity=daily, 93. On targets and search terms, the heaviest resources, those drop to 93 and 31. Asking for more returns an error naming the exact limit. Both dates are included in the range.
• Lists paginate in two different ways. Catalog and structure resources use a cursor (starting_after); metrics resources use limit and offset. In both cases has_more tells you whether another page follows.
• There is a request limit per token. If you exceed it you get a 429 and simply need to retry more slowly.

Parameters and responses of each endpoint

The table above says which resources exist. To see the input parameters and the exact shape of each response, there are two routes:

• Browsable reference — every endpoint with its parameters, their types and an example response. Generated from the API itself, so it cannot fall out of date. In English.
• OpenAPI schema — the raw OpenAPI 3.0 document, to import into Postman, Insomnia or a client generator. No token needed.