rest api

REST API

The same fourteen reads as the MCP server, exposed as versioned GET endpoints so you can script against Origin without an MCP client. For identical parameters an endpoint’s data is byte-for-byte the tool’s structuredContent.

Base URL#

url

https://mcp.originattribution.com/v1

Authentication#

Every request carries an Origin API key as a bearer token. Create keys in the Origin app under Settings → API keys. OAuth tokens issued to MCP clients are not accepted here; the REST API is bearer-key only.

curl "https://mcp.originattribution.com/v1/shop" \
  -H "Authorization: Bearer org_..."

Response envelope#

Every response is JSON with Cache-Control: no-store. Successful responses wrap the data; failures carry a message and the matching status code.

json

// 200
{ "success": true, "data": { ... } }

// 4xx / 5xx
{ "success": false, "error": "Invalid query parameter \"days\": Too big: expected number to be <=365" }

Query parameters#

Parameters are the same as the corresponding MCP tool’s inputs, passed in the query string. days, limit, id and attribution_window are parsed as numbers; everything else stays a string, so Shopify IDs (order_id, customer_id) are digit strings. A parameter given more than once is rejected. The shared attribution parameters are described on the MCP server page.

Endpoints#

Each endpoint maps to one MCP tool and returns the same fields. Full descriptions of what each one returns are on the MCP server page.

Field	Type	Description
/v1/shop	`get_shop_overview`	No parameters.
/v1/store/metrics	`get_store_metrics`	`days`
/v1/channels	`get_channels`	`days`, `sort_by`, `attribution_model`, `attribution_window`
/v1/utm/top-sets	`get_top_utm_sets`	`days`, `limit`, `sort_by`, `attribution_model`, `attribution_window`
/v1/utm/top-parameters	`get_top_utm_parameters`	`days`, `attribution_model`, `attribution_window`
/v1/utm/set-metrics	`get_utm_set_metrics`	`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `days`, `attribution_model`, `attribution_window`
/v1/utm/parameter-metrics	`get_utm_parameter_metrics`	`parameter`, `value`, `days`, `attribution_model`, `attribution_window`
/v1/ads/top	`get_top_ads`	`level`, `days`, `limit`, `sort_by`, `attribution_model`, `attribution_window`
/v1/ads/metrics	`get_ad_metrics`	`level`, `id`, `days`, `attribution_model`, `attribution_window`
/v1/ads/platforms	`get_top_ad_platforms`	`days`, `attribution_model`, `attribution_window`
/v1/orders/touchpoints	`get_order_touchpoints`	`order_name` or `order_id`
/v1/orders/customer-events	`get_order_customer_events`	`order_name` or `order_id`, `limit`
/v1/customers/touchpoints	`get_customer_touchpoints`	`customer_id`
/v1/customers/events	`get_customer_events`	`customer_id`, `limit`

Examples#

API=https://mcp.originattribution.com/v1
KEY=org_...

# Store context: currency, timezone, connected ad platforms
curl -s "$API/shop" -H "Authorization: Bearer $KEY"

# Top 5 UTM sets by ROAS, last 30 days, last-touch attribution
curl -s "$API/utm/top-sets?days=30&limit=5&sort_by=roas" \
  -H "Authorization: Bearer $KEY"

# One campaign under first-touch attribution with a 7-day window
curl -s "$API/ads/metrics?level=ad_campaign&id=123&attribution_model=FIRST_TOUCH&attribution_window=7" \
  -H "Authorization: Bearer $KEY"

# Where did order #1234 come from? (the # must be URL-encoded)
curl -s "$API/orders/touchpoints?order_name=%231234" \
  -H "Authorization: Bearer $KEY"

# A customer's last 50 storefront events
curl -s "$API/customers/events?customer_id=7000000001&limit=50" \
  -H "Authorization: Bearer $KEY"

Status codes#

text

200   success
400   a query parameter failed validation (the message names it), or both / neither of order_name and order_id
401   missing, malformed, unknown or revoked key (WWW-Authenticate: Bearer)
403   inactive Origin subscription, or an attribution window the plan does not include
404   unknown path, an ad entity the store does not own, an order or customer Origin has no record of
405   any method other than GET (Allow: GET)
429   rate limit exceeded (Retry-After: 60)
502   Origin's analytics service could not answer
500   anything else

Limits#

Each API key may make 60 requests per minute, shared with MCP tool calls made with the same key. Ranking endpoints return at most 20 rows and journey endpoints at most 1000 events per request; there is no further pagination. There are no write endpoints.

warningA store whose Origin subscription is not active authenticates successfully but receives a 403 from every endpoint instead of data.