# 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`](/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:

```bash
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](../ai/mcp-overview.md), 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.

```json
{
  "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.

```json
{ "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)

```json
"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.

```bash
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.

```bash
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).

```bash
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.

```bash
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. |

```bash
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](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.

```bash
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. |

```bash
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. |

```bash
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.

```bash
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`. |

```bash
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`. |

```bash
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`. |

```bash
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. |

```bash
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.

```bash
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.

```bash
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.

```bash
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.

## Related

- [MCP overview](../ai/mcp-overview.md)
- [Send events with the SDK](../get-started/send-events-sdk.md)
- [Integrating with CoreX](../meet-corex/integrating.md)
