Home Getting Started Developer API

Developer API

Last updated on Sep 04, 2026

Ranksy has a REST API for sending data in and pulling data out from your own code — enrich merchant records, record activity and usage events, and read back usage, rankings, reviews, traffic, and more. The full endpoint reference lives at api.ranksyapp.com.

What It's For

  • Send data in — enrich a merchant with /identify, and record what happens with /track (both activity and usage events).

  • Pull data out — read your usage totals, rankings, reviews, traffic, and competitor data programmatically instead of by hand.

Create an API Key

  1. Go to Settings → API Keys.

  2. Create a key and pick the scopes it needs (see below).

  3. Copy the key — it starts with rk_live_ and is shown once. Store it somewhere safe.

⚠️ Treat an API key like a password. Don't commit it to a repo or ship it in client-side code. If one leaks, delete it from Settings → API Keys and create a new one.

Making a Request

The base URL is https://ranksyapp.com/api/v1. Send your key as a Bearer token. The {app} in a URL is the ULID of the app the request is about.

curl https://ranksyapp.com/api/v1/apps/{app}/usage-metrics \
  -H "Authorization: Bearer rk_live_..."

curl -X POST https://ranksyapp.com/api/v1/apps/{app}/track \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "myshopify_domain": "store.myshopify.com", "event_handle": "messages_sent", "attributes": { "value": 12 } }'

Scopes

Each key carries only the scopes you grant it, so give a key the least it needs. The available scopes:

Scope Grants
crm:read / crm:write Read / enrich merchant CRM records (/identify, /track)
appevents:write Record and forward Shopify App Events via /track
usage:read Read usage metrics and usage events
rankings:read Keyword and category rankings
reviews:read App reviews
traffic:read Traffic and attribution
competitors:read Competitor data
apps:read Your apps
metrics:read · catalog:read · scorecard:read · capi:write Metrics, catalog, scorecard, conversions

The exact scope each endpoint needs is listed on its reference page.

Rate Limits

Each key is limited to 120 requests per minute and 50,000 requests per day. Go over and you get a 429 — back off and retry.

Common Endpoints

  • /identify — enrich a merchant (plan, address, contacts, tags). See Connect Partner API for the data it pulls.

  • /track — record an activity or usage event.

  • /usage-metrics — per-handle usage totals over a date range.

  • /reviews, /rankings, /traffic — read the same data you see in the dashboard.

Full request and response shapes for every endpoint are at api.ranksyapp.com.

API, CLI, or AI Assistant (MCP)

Three ways to reach your data, for three different jobs:

  • Developer API — your app or scripts, reading and writing programmatically. API keys, REST.

  • AI Assistant (MCP) — you, exploring your data conversationally. Browser authorization, no code.

  • Ranksy CLI — scripts, cron jobs, and CI checks from your terminal. One binary, same API key.

Next Steps