Skip to content

Accounts and connections ​

Start here. GET /v1/me reports which scopes and accounts your key reaches, and is the cheapest way to check that a key works.

Servers​

https://api.epinium.com

me​

Describes the authenticated API key: its scopes and accessible accounts. No scope required — any valid key can call it.

Operations​


Describe the authenticated credential (API key or OAuth grant): scopes and accessible accounts​

GET
/v1/me

Authorizations​

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters​

Query Parameters

include_onboarding

Set to true to add onboarding to every account: the onboarding steps done and pending, the next one, whether the first data download finished and the link to connect channels.

Type
string
Valid values
"true""false"

Responses​

200

application/json
JSON
{
  
"object": "string",
  
"id": "string",
  
"subject_type": "string",
  
"scopes": [
  
  
"string"
  
],
  
"account_required": true,
  
"accounts": [
  
  
{
  
  
  
"id": "string",
  
  
  
"name": "string",
  
  
  
"onboarding": {
  
  
  
  
"steps": [
  
  
  
  
  
{
  
  
  
  
  
  
"key": "string",
  
  
  
  
  
  
"done": true,
  
  
  
  
  
  
"completed_at": "string",
  
  
  
  
  
  
"skipped": true
  
  
  
  
  
}
  
  
  
  
],
  
  
  
  
"next_step": "string",
  
  
  
  
"initial_sync_completed": true,
  
  
  
  
"ads_initial_sync_completed": true,
  
  
  
  
"connections_url": "string"
  
  
  
}
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​


accounts​

Accounts this API key can operate on, selectable via the Epinium-Account header. Requires connections:read.


List the accounts this API key can operate on​

GET
/v1/accounts

Authorizations​

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Responses​

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"id": "string",
  
  
  
"name": "string",
  
  
  
"connections": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground​

Authorization

Samples​


connections​

The authenticated account's data source connections. Requires connections:read.


List the authenticated account's connections​

GET
/v1/connections

Authorizations​

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters​

Query Parameters

limit

Page size. The default is enough to explore; raise it only when you need to walk a whole collection.

Type
integer
Example20
Default
20
Minimum
1
Maximum
100
starting_after

Cursor for the next page: the id of the last record you received. Returns the records after it.

Type
string
ending_before

Cursor for the previous page: the id of the first record you received. Returns the records before it.

Type
string
expand

Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.

fields

Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. An unknown key or field name is rejected with a 400 that lists the valid ones.

Type
object
search

Case-insensitive substring match over the connection name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.

Type
string
Min Length
1
Max Length
200
include_total

Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.

Type
string
Valid values
"true""false"
type
Type
string
Valid values
"seller""vendor""adv-profile""shopify""woocommerce"

Responses​

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"type": "string",
  
  
  
"name": "string",
  
  
  
"active": true,
  
  
  
"countries": [
  
  
  
  
[
  
  
  
  
  
"string"
  
  
  
  
]
  
  
  
],
  
  
  
"createdAt": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground​

Authorization
Variables
Key
Value

Samples​


GET /v1/connections/{id}​

GET
/v1/connections/{id}

Authorizations​

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

expand

Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.

fields

Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. An unknown key or field name is rejected with a 400 that lists the valid ones.

Type
object

Responses​

200

application/json
JSON
{
  
"id": "string",
  
"type": "string",
  
"name": "string",
  
"active": true,
  
"countries": [
  
  
[
  
  
  
"string"
  
  
]
  
],
  
"createdAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


List the sync runs of a connection, newest first​

GET
/v1/connections/{id}/sync-runs

Authorizations​

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

limit

How many runs to return, newest first (1 to 31, default 1). Each run is billed as one row.

Type
integer
Default
1
Minimum
1
Maximum
31

Responses​

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"id": "string",
  
  
  
"connection_id": "string",
  
  
  
"trigger": "string",
  
  
  
"status": "string",
  
  
  
"reason_code": "string",
  
  
  
"started_at": "string",
  
  
  
"finished_at": "string",
  
  
  
"deadline_at": "string",
  
  
  
"milestones": {
  
  
  
  
"catalog_done_at": "string",
  
  
  
  
"amazon_ready_at": "string",
  
  
  
  
"readable_at": "string"
  
  
  
},
  
  
  
"parts": [
  
  
  
  
{
  
  
  
  
  
"key": "string",
  
  
  
  
  
"scope": "string",
  
  
  
  
  
"informative": true,
  
  
  
  
  
"state": "string",
  
  
  
  
  
"has_errors": true
  
  
  
  
}
  
  
  
],
  
  
  
"markets": [
  
  
  
  
{
  
  
  
  
  
"country_id": "string",
  
  
  
  
  
"code": "string",
  
  
  
  
  
"catalog": {
  
  
  
  
  
  
"status": "string",
  
  
  
  
  
  
"reason_code": "string",
  
  
  
  
  
  
"finished_at": "string"
  
  
  
  
  
},
  
  
  
  
  
"rows": {
  
  
  
  
  
  
"orders": 0,
  
  
  
  
  
  
"sales_traffic": 0,
  
  
  
  
  
  
"economics": 0,
  
  
  
  
  
  
"vendor_analytics": 0
  
  
  
  
  
}
  
  
  
  
}
  
  
  
],
  
  
  
"account_parts": [
  
  
  
  
{
  
  
  
  
  
"key": "string",
  
  
  
  
  
"expected": 0,
  
  
  
  
  
"data": 0,
  
  
  
  
  
"empty": 0,
  
  
  
  
  
"failed": 0,
  
  
  
  
  
"expired": 0,
  
  
  
  
  
"finished_at": "string",
  
  
  
  
  
"failures": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"label": "string",
  
  
  
  
  
  
  
"status": "string",
  
  
  
  
  
  
  
"reason_code": "string"
  
  
  
  
  
  
}
  
  
  
  
  
]
  
  
  
  
}
  
  
  
],
  
  
  
"product_details": [
  
  
  
  
{
  
  
  
  
  
"endpoint": "string",
  
  
  
  
  
"markets": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
  
"status": "string",
  
  
  
  
  
  
  
"last_completed_at": "string"
  
  
  
  
  
  
}
  
  
  
  
  
]
  
  
  
  
}
  
  
  
]
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground​

Authorization
Variables
Key
Value

Samples​


onboarding​

Skip an onboarding step of the account, or take it up again. No scope required, so a read-only key can store that the person does not want Amazon Ads.


Skip an onboarding step of the account, or take it up again​

PATCH
/v1/onboarding/steps/{key}

Authorizations​

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required
Valid values
"connect_channel""connect_advertising""create_brand""add_competitors""create_cluster""create_prompt""add_product_costs""optimize_listings""publish_listing_changes""clone_workflow_template""activate_workflow""first_workflow_run"

Request Body​

application/json
JSON
{
  
"skipped": true
}

Responses​

200

application/json
JSON
{
  
"steps": [
  
  
{
  
  
  
"key": "string",
  
  
  
"done": true,
  
  
  
"completed_at": "string",
  
  
  
"skipped": true
  
  
}
  
],
  
"next_step": "string",
  
"initial_sync_completed": true,
  
"ads_initial_sync_completed": true,
  
"connections_url": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Powered by VitePress OpenAPI

Epinium Documentation