REST API

Manage apps, links and integrations, read analytics and subscriptions, and send server-side events from your own backend.

All endpoints live under https://apprefer.com/api/v1 (on a self-hosted AppRefer, your own domain). The API is for servers: an organisation API key is a secret, so never put one in an app or a web page. Apps talk to AppRefer through the SDKs with the public pk_ SDK key instead.

Agent workspace and login endpoints

POST /api/agent/workspaces starts a test workspace with a scoped seven-day key and human claim link. GET /api/agent/workspaces/{id} returns its credential-bound status. Existing access-request endpoints remain supported. For exact payloads, limits, MCP OAuth discovery, PKCE, rotating tokens, approvals and revocation, read auth.md and AI agents & MCP.

Authentication

Send an organisation API key as a bearer token on every request:

GET /api/v1/apps
Authorization: Bearer ak_live_...

• Create keys in the dashboard under API keys (account menu at the foot of the sidebar). You need the admin role. The full key is shown once; AppRefer stores only its hash.
• A key belongs to one company and reaches only that company's apps. Any other app id answers 404, exactly like an app that doesn't exist.
• Revoking a key in the dashboard stops it everywhere within a minute.

Scopes

Each key carries a list of scopes. A request without the scope its endpoint needs gets 403 FORBIDDEN, and the message names the scope. Give each key only what its job needs, for example users:erase alone for an account-deletion worker. The dashboard offers three presets: Full Access (*), Read Only (the five :read scopes for analytics, apps, links, integrations and SKAN) and Analytics Only.

Responses and errors

Most endpoints wrap their result in data; lists that page add meta. Errors use one shape:

{ "data": { "appId": "app_3f9c2a1b7d4e", "name": "Sparkly" } }

{ "error": { "code": "FORBIDDEN", "message": "Missing required scope: links:write" } }

A few server-to-server endpoints answer without the data wrapper, because their callers retry on the status alone: users/erase and its status, web-events (errors are { "error": { "code": "invalid_click_id" } }), web-purchases (errors are { "error": "message" }) and the support agent endpoints.

Rate limits

Requests from all of a company's keys share one one-minute window. A request is refused with 429 once the window already holds more requests than that endpoint allows. The response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Back off and retry after the reset.

Pagination

/attributions and /events page with a cursor. Pass limit (1 to 500, default 50) and, for the next page, the cursor from the previous response. When meta.hasMore is false there is nothing more. Other lists return everything in one response.

{
  "data": [ ... ],
  "meta": { "cursor": "eyJpZCI6ImFwcF8zZjljX2Rldl8xMjMifQ==", "hasMore": true }
}

Analytics endpoints take days (1 to 365, default 14) and report live (production) data only. Revenue is net USD: paid revenue minus refunds.

Endpoints

Paths below are relative to /api/v1.

Apps

App settings you can change with PATCH /apps/{appId}:

curl -X PATCH "https://apprefer.com/api/v1/apps/app_3f9c2a1b7d4e" \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "probabilisticMatching": false, "trackingConsentRequired": true }'

{ "data": { "appId": "app_3f9c2a1b7d4e", "updated": ["trackingConsentRequired", "probabilisticMatching"] } }

Tracking links

The returned url depends on the network: /api/c/ for most, /g/ for Google Ads, /o/ for ChatGPT Ads and /x/ for X Ads (which also needs a clean HTTPS storeUrl). See Tracking links.

curl -X POST "https://apprefer.com/api/v1/apps/app_3f9c2a1b7d4e/links" \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "linkId": "spring-sale", "name": "Spring sale", "network": "meta" }'

{
  "data": {
    "id": "spring-sale",
    "name": "Spring sale",
    "network": "meta",
    "url": "https://apprefer.com/api/c/spring-sale",
    "destinationMode": "legacy_redirect",
    "storeUrl": "",
    "clicks": 0,
    "installs": 0
  }
}

Integrations

Fields per network are on each integration page: Meta, Google, TikTok, ChatGPT Ads, X Ads, RevenueCat. The support network holds push and email delivery (see Support).

Analytics

Event names and properties are described in Events.

Billing and subscriptions

curl "https://apprefer.com/api/v1/apps/app_3f9c2a1b7d4e/billing/customers/user_8421" \
  -H "Authorization: Bearer ak_live_..."

{
  "data": {
    "appUserId": "user_8421",
    "entitlements": {
      "premium": {
        "id": "premium",
        "isActive": true,
        "productId": "com.example.app.annual",
        "store": "app_store",
        "expiresAtMs": 1792000000000,
        "willRenew": true,
        "periodType": "normal",
        "state": "active",
        "subscriptionKey": "2000000123456789"
      }
    },
    "activeSubscriptions": ["com.example.app.annual"],
    "requestDateMs": 1760870400000
  }
}

Set-up, store notifications and the outbound webhook are covered in Billing; the catalogue and experiments in Offerings; metric definitions in Subscription analytics.

Website conversions

Payloads and network mapping: Events, ChatGPT Ads and X Ads.

End users

What is erased and what is kept for accounting: Privacy.

Support

Field-by-field details: Support.

SKAdNetwork and AdAttributionKit

See SKAdNetwork.

Calling the API

curl "https://apprefer.com/api/v1/apps/app_3f9c2a1b7d4e/campaigns?days=30&groupBy=adgroup" \
  -H "Authorization: Bearer $APPREFER_API_KEY"

Self-hosted operator endpoints

/api/v1/admin/* (organisations, their apps and stats, one app and its links) accept only the deployment's platform admin key (ak_admin_, the APPREFER_ADMIN_KEY set on the server), never an organisation key. The same admin key is also accepted by the billing configuration, readiness and help article endpoints above. They exist for whoever runs an AppRefer deployment.