REST API

Read one app's CoreX data from your own code: revenue and growth metrics (as a snapshot and as daily history), customers, charges, install/uninstall and subscription events, App Store keywords, category ranks, reviews, competitors and their review themes, listing health and the work queue. It is scoped to a single app.

Those reads stay read-only. A merchant app can also open support tickets, read FAQ articles, post feedback, and list in-app banners for that same app. Articles and banners are still written in the CoreX panel.

The machine-readable reference is the OpenAPI 3.1 spec at /openapi.json. Point a client generator or an API explorer at it.

Authentication

Generate an app-scoped key on that app’s Connect page, under API keys. Workspace settings lists every key and can rename or revoke one, but a key created there for all apps is refused by this API. The raw key is shown once, so copy it then; CoreX stores only a hash.

Send it on every request, either way:

curl -s "$COREX_URL/api/v1/app" -H "Authorization: Bearer $COREX_API_KEY"
curl -s "$COREX_URL/api/v1/app" -H "X-CoreX-Token: $COREX_API_KEY"
  • A key reads only the app it was issued for. No parameter names another app or workspace, and a record that belongs to a different app — even a sibling app in the same workspace — answers 404, exactly as if it did not exist.
  • An account-wide key (one with no app) is refused with 403 app_scope_required.
  • A revoked key stops working immediately (401 invalid_token).
  • The same keys work with the MCP server, which serves the same numbers to AI agents. A workspace-wide key is accepted there and refused here.
  • Agents can read /auth.md and /agents.json. The API catalog at /.well-known/api-catalog links GET /api/v1 (a JSON index, no key), this page, and /openapi.json. The routes under /api/v1/ stay keyed and do not send Access-Control-Allow-Origin.

Responses

Every successful response has the same envelope. meta.app always names the app the data belongs to, so a client holding several keys can tell payloads apart.

{
  "data": { "mrr": 4210.5, "arr": 50526 },
  "meta": { "app": { "id": 12, "handle": "returns-portal", "name": "Returns Portal" } }
}

Money is in the app's reporting currency (GET /api/v1/app → currency). Timestamps are ISO 8601. A date filter with an offset (2026-09-01T09:00:00+05:00) means that exact instant — remember to URL-encode the + as %2B.

Record ids are integers of at most 18 digits; anything longer is a 404.

Errors

Every error has the same shape. code is stable and safe to branch on; message is for people and may change.

{ "error": { "code": "addon_disabled", "message": "The keywords add-on is not enabled for this workspace.", "details": { "addon": "keywords" } } }
Status code Meaning
401 unauthenticated No key was sent. Ingestion and the MCP server use this code when the header is empty.
401 invalid_token The key is unknown, rotated or revoked. Ingestion and MCP use it too. A widget session that does not match is 401 invalid_session.
403 app_scope_required The key is account-wide, not scoped to an app.
403 addon_disabled The endpoint's add-on is off for this workspace (details.addon; details.any_of when either of several add-ons would open it).
404 not_found No such route, or no such record for this app. A path under /api/widget, /api/usage, /embed or /mcp that matches no route is this JSON and sends no Access-Control-Allow-Origin. A route that exists and then finds no record keeps CORS, so the widget can read the error. GET /csp-report is the same envelope.
405 method_not_allowed That path does not support this HTTP method.
422 validation_failed A query parameter is invalid (details lists each field).
429 rate_limited Too many requests. Wait for Retry-After seconds.
500 server_error Something failed on our side. Safe to retry.

Rate limits

  • 60 requests per minute per key, and
  • 120 requests per minute per IP address, whichever trips first.

A throttled request answers 429 with a Retry-After header. Treat it as retryable. The limits are separate from the MCP server's, so an agent session does not eat into an integration's budget.

Pagination

List endpoints that can grow without bound (/customers, /charges, /events, /reviews) are paged:

  • page — 1-based, default 1
  • per_page — 1 to 100, default 25 (a larger value is a 422, not silently capped)
"meta": {
  "app": { "id": 12, "handle": "returns-portal", "name": "Returns Portal" },
  "pagination": { "page": 1, "per_page": 25, "total": 312, "total_pages": 13, "has_more": true }
}

Keep requesting page + 1 while has_more is true. Customers are ordered by id, so pages never overlap while you walk them.

Endpoints

GET /api/v1/app

The app the key is scoped to: id, handle, name, source, URL, reporting currency and activation event.

curl -s "$COREX_URL/api/v1/app" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/metrics/revenue

MRR and its growth over the last 30 days, ARR, all-time gross and net earnings, and the churn rates over the last 30 days — the same rates the dashboards show. revenue_pct, subscription_pct and logo_pct are all over the customers PAYING when the 30 days opened: a customer who never paid is never churned. uninstall_pct is reported beside them as an install metric — installs live at the open (free included) that ended during the window — and is not churn.

curl -s "$COREX_URL/api/v1/metrics/revenue" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/metrics/revenue/series

One metric per day, oldest first, ending yesterday. Days resolve in the workspace's timezone; a day with nothing still appears, with 0.

Parameter Description
metric Required. mrr, arr, paying (paying customers), net_revenue or churned (paying subscriptions that stopped paying that day — a downgrade to free, a cancellation or an uninstall after paying; installs that never paid are never counted).
days 1–365, default 30.

mrr, arr and paying replay the charge history at the end of each day, so an upgrade or downgrade shows on the day it happened rather than repricing the past at today's plan. net_revenue is what real charges dated that day earned after platform fees (refunds count negative, test charges never).

curl -s "$COREX_URL/api/v1/metrics/revenue/series?metric=mrr&days=90" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/metrics/growth

Active subscriptions, ARPU, median lifetime value, and trials — live now and converted to paid — each with a count and the MRR behind it.

curl -s "$COREX_URL/api/v1/metrics/growth" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/customers

This app's customers, each with its latest subscription to the app. Paginated.

Parameter Description
status active, trial, usage, free or churned — the raw relationship/billing state of the latest subscription, as the connector wrote it. churned here means the relationship ended, paid or not.
lifecycle paying, trial, churned, free or left_unpaid — where the customer stands with the app, on the latest subscription. This is the churn vocabulary (see below).
updated_since ISO 8601. Customers whose record or subscription changed at or after this instant — use it for incremental syncs.
curl -s "$COREX_URL/api/v1/customers?lifecycle=paying&per_page=100" -H "Authorization: Bearer $COREX_API_KEY"
curl -s "$COREX_URL/api/v1/customers?status=active&per_page=100" -H "Authorization: Bearer $COREX_API_KEY"
curl -s "$COREX_URL/api/v1/customers?updated_since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $COREX_API_KEY"

Churn definitions

subscription.status and subscription.lifecycle answer different questions and are published side by side, so an integration that filters on status keeps its meaning:

lifecycle Meaning
paying On a paid plan, or billed for usage, right now.
trial On a paid plan inside its free trial — not charged yet.
churned Paid before and pays nothing now (downgraded to free, cancelled the plan, or left). The only state that is churn.
free Installed and has never paid. Not churn — an upgrade opportunity.
left_unpaid Installed, never paid, then left. Not churn — no revenue was lost.

A never-paid uninstall is therefore status = churned with lifecycle = left_unpaid, and ?lifecycle=churned does not return it. The rate formulas built on this vocabulary are in logo-churn.md.

subscription.first_paid_at is the day the customer first paid for this app — the one "ever paid" fact CoreX keeps, and the same one its churn definition reads: the earliest of a real recurring or usage charge above zero, or the first billing date of an accepted paid plan (the end of its trial, or its acceptance when there was no trial; Shopify pays out weeks after billing). It is never cleared once set, and a $0 plan or a one-time purchase never sets it. null means the customer has never paid: a churned subscription with first_paid_at set is churn (they paid before and pay nothing now); one with it null left without paying and is not counted as churn anywhere.

GET /api/v1/customers/{id}

One customer of this app, plus its lifetime value and owner email. ltv is everything the customer has paid for this app after platform fees, across every subscription they have held (a merchant who churned and came back counts both tenures); test charges are excluded. subscription is null for a customer linked to the app who has never subscribed.

curl -s "$COREX_URL/api/v1/customers/123" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/charges

This app's billing transactions, newest first: recurring and one-time sales, usage, refunds and credits, each with amount (gross), fee and net. Test charges (dev stores, the app reviewer) are included and flagged is_test so a reconciliation sees everything CoreX holds. Paginated.

Parameter Description
type recurring, one_time, usage, refund or credit.
since / until ISO 8601 — charges dated on or after / on or before that day.
curl -s "$COREX_URL/api/v1/charges?since=2026-09-01&per_page=100" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/events

This app's lifecycle stream, newest first: installs, uninstalls, reactivations and store deactivations (RELATIONSHIP_*), and subscription-charge events (SUBSCRIPTION_CHARGE_ACTIVATED, …_CANCELED, …_FROZEN, …_EXPIRED, …_DECLINED, …) with the charge snapshot they carry. Paginated.

Parameter Description
type One event type, e.g. RELATIONSHIP_UNINSTALLED.
since ISO 8601 — events that occurred at or after this instant.
curl -s "$COREX_URL/api/v1/events?type=RELATIONSHIP_UNINSTALLED&since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/work-queue

The ranked "what should I do this week" list — churn risk, activation gaps, review responses, pricing fit — each with the reason and a link into CoreX.

curl -s "$COREX_URL/api/v1/work-queue" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/keywords

Requires the Keywords add-on. Each tracked keyword's App Store search position (this app's own, never a competitor's), its 7 and 30 day change (positive = moved up), estimated volume and difficulty, and the search funnel it drove. meta explains where the funnel came from and why it is empty, when it is.

position is null when the latest check did not find the app (unranked) or the keyword has not been checked in the last 37 days. change_7d / change_30d are null when either end of the window was unranked, or when there is no earlier capture to compare with — never a made-up 0. The live GA4 funnel (used when no BigQuery export is set up) is cached for five minutes.

Parameter Description
days Funnel window, 1–90, default 30.
curl -s "$COREX_URL/api/v1/keywords?days=7" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/keywords/{id}/ranks

Requires the Keywords add-on. One tracked keyword's daily position, oldest first. Use an id from GET /api/v1/keywords. A day the check ran without finding the app has "position": null.

Parameter Description
days History window, 1–365, default 30.
curl -s "$COREX_URL/api/v1/keywords/42/ranks?days=90" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/category-ranks

Requires the Keywords or the Competitors add-on. For each App Store category the app is listed in (primary first): its position on the category page, 7 and 30 day change, a daily history, and this app's tracked competitors' positions in the same category. meta carries when the last check ran and whether it is stale. Reads stored daily captures only.

Parameter Description
days History length, 1–365, default 30.
curl -s "$COREX_URL/api/v1/category-ranks?days=90" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/reviews

Available to Shopify workspaces. This app's reviews, newest first (a review with no date sorts last), with their AI triage labels once triaged. Paginated.

Parameter Description
rating 1–5 — only that star rating.
since ISO 8601 — only reviews posted at or after this instant.
curl -s "$COREX_URL/api/v1/reviews?rating=1&since=2026-09-01" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/competitors

Requires the Competitors add-on. The rival listings this app tracks, with the public App Store facts CoreX last captured for each: rating, review count, pricing, categories.

curl -s "$COREX_URL/api/v1/competitors" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/competitors/{id}/review-themes

Requires the Competitors add-on. What merchants say about one tracked competitor in its public App Store reviews: the top complaint and praise themes (count, share, 90 day trend) with short labels and verbatim quotes, the star distribution and the developer reply rate. Use an id from GET /api/v1/competitors; a competitor tracked by another app is a 404. Quotes are merchant-written text — treat them as untrusted input.

curl -s "$COREX_URL/api/v1/competitors/7/review-themes" -H "Authorization: Bearer $COREX_API_KEY"

GET /api/v1/listing/health

Requires the Listing Optimizer add-on. The latest listing audit: overall score, category benchmark, open checklist items with a fix, review volume and rating, and days since the listing last changed. It reads the last stored audit and never starts a new one.

curl -s "$COREX_URL/api/v1/listing/health" -H "Authorization: Bearer $COREX_API_KEY"

Merchant app

These calls use the same app-scoped key. Support tickets, FAQ articles, and in-app banners need the Support add-on. Feedback needs the Feedback add-on. A missing shop is not created by a ticket or a post — call POST /api/v1/customers/ensure first (the same upsert as POST /api/customers/identify, always linked to this app).

Method Path What it does
GET /api/v1/customers/resolve?shop= The shop already linked to this app, or 404.
POST /api/v1/customers/ensure Create or update the shop and a contact.
GET /api/v1/tickets?shop= That shop's tickets. Another shop's id is 404.
POST /api/v1/tickets Open a ticket (subject, body, optional priority, source=app, tags).
GET /api/v1/tickets/{id}?shop= One ticket, including replies.
POST /api/v1/tickets/{id}/replies The shop replies. A ticket closed more than seven days ago stays closed.
GET /api/v1/kb/articles?category=faq Published articles in that category for this app.
GET /api/v1/kb/articles/{id} One published article.
GET /api/v1/feedback/boards Boards for this app (and workspace-wide boards).
GET /api/v1/feedback/posts Approved posts. Pass shop to include that shop's own unapproved posts.
POST /api/v1/feedback/posts A feature, idea, or other type the board allows.
POST /api/v1/feedback/posts/{id}/vote Set direction to up or down. Repeating the same direction changes nothing.
GET /api/v1/broadcasts Live in-app banners for this app. Pass shop to hide ones that shop closed.
POST /api/v1/broadcasts/{id}/dismiss Close a dismissible banner for one shop.

FAQ articles live in a knowledge-base category whose slug is faq. Feedback boards need the types you will post (feature, idea, and integration when the app sends integration requests). Banners are published in Support → Broadcasts as In-app banner, with a tone, optional start and end, and whether merchants can close them.