Rank Sonar
All docs

Developer

REST API reference

Programmatically read and modify your Rank Sonar workspace via the public REST API.

The Rank Sonar API lives at https://api.ranksonar.io. Available on Studio and above.

Authentication

API requests require a Bearer token. Generate one in Settings → API keys → Create key.

Authorization: Bearer rsk_live_xxxxxxxxxxxxxxxx

API keys are scoped to a single workspace. To access multiple workspaces, generate one key per workspace.

Rate limit: 100 requests per minute per key. Exceeding returns 429 Too Many Requests with Retry-After header.

Versioning

The current API version is v1. We prefix all routes with /v1. Breaking changes will increment the version; we commit to supporting v1 for at least 12 months after v2 is released.

Endpoints

List apps

GET /v1/apps

Response:

{
  "data": [
    {
      "id": "app_01H8Z9...",
      "name": "Forktastic",
      "appleId": "1234567890",
      "googleId": null,
      "isActive": true,
      "createdAt": "2026-04-12T10:00:00Z"
    }
  ]
}

Add app

POST /v1/apps
Content-Type: application/json

{ "url": "https://apps.apple.com/us/app/forktastic/id1234567890" }

List keywords for an app

GET /v1/apps/{appId}/keywords?store=apple&country=us

Response:

{
  "data": [
    {
      "id": "kw_01H8Z9...",
      "term": "meal planner",
      "isFavorite": true,
      "addedAt": "2026-04-12T10:01:00Z",
      "currentRank": 4,
      "chanceScore": 78.5
    }
  ]
}

Add keywords (bulk)

POST /v1/apps/{appId}/keywords
Content-Type: application/json

{ "terms": ["meal planner", "recipe app", "grocery list"] }

Get rankings timeseries

GET /v1/apps/{appId}/keywords/{kwId}/rankings?from=2026-04-01&to=2026-05-01

Response:

{
  "data": [
    { "date": "2026-04-01", "rank": 8 },
    { "date": "2026-04-02", "rank": 6 },
    { "date": "2026-04-03", "rank": 5 }
  ]
}

List events

GET /v1/events?type=rank_change&since=2026-05-01T00:00:00Z&limit=50

Get a specific app's metadata snapshot

GET /v1/apps/{appId}/metadata?country=us&store=apple

Trigger Copilot generation

POST /v1/apps/{appId}/copilot/generate
Content-Type: application/json

{ "types": ["keyword_opportunity", "subtitle_rewrite"] }

Returns a workflowRunId you can poll for status.

Error format

All errors return a JSON body:

{
  "error": "Invalid app ID",
  "code": "app_not_found",
  "requestId": "req_01H8Z9..."
}

Status codes follow standard HTTP semantics:

  • 200 — success
  • 400 — invalid request (validation failed)
  • 401 — invalid or missing API key
  • 403 — API key doesn't have permission for the requested resource
  • 404 — resource not found
  • 429 — rate limit exceeded
  • 500 — server error (please report with the requestId)

SDKs

There are no official SDKs at v1. The API is small enough that direct fetch calls in your language of choice are typically simpler than maintaining an SDK.

If you build a community SDK, let us know and we'll feature it here.

See also