AsoBeast Rankings API

openapi: 3.2.0
info:
  title: asobeast Rankings API
  description: 'Self hosted ASO toolkit API.


    A metered instance carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every response, for the tightest limit the request touched. A self hosted instance has no request rate limits and sends no such header. Limits are per workspace, so minting more tokens does not buy more capacity, and they are sized per plan across three classes: read for stored data, write for configuration changes and store for the endpoints that reach the App Store or Google Play.


    A 429 carries Retry-After and a rateLimit object naming the window that closed, or an aiAllowance object when the workspace has spent the AI calls its plan includes this month. A 403 with a quota object means a plan capacity limit such as apps or tracked keyword markets, which is a different problem from a rate limit. A 402 with an entitlement object means the workspace needs a plan.


    Positions are 1-based and null means checked but not found within the captured depth, never zero. Daily granularity uses UTC dates.'
  version: 1.15.0
  contact: {}
servers:
- url: http://localhost:3000/api/backend
  description: Web origin proxy
- url: http://localhost:4000
  description: Direct API
security:
- personalApiToken: []
tags:
- name: Rankings
paths:
  /apps/{id}/rankings:
    get:
      operationId: RankingsController_history
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: from
        required: false
        in: query
        schema:
          type: string
      - name: to
        required: false
        in: query
        schema:
          type: string
      - name: keywordIds
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Ranking history series for an app
      tags:
      - Rankings
  /apps/{id}/serp-movers:
    get:
      operationId: RankingsController_serpMovers
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: days
        required: true
        in: query
        schema:
          minimum: 1
          maximum: 30
          default: 7
          allOf:
          - $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Apps that broke into the top 10 for tracked keywords
      tags:
      - Rankings
  /keywords/{keywordId}/serp:
    get:
      description: Answers up to 50 entries of the day asked for, or of the newest captured day. Each entry carries its iconUrl, titleMatch and titleSegments, and previous, delta and movement against comparedTo, the newest captured day before date. Movement is none when there is no earlier capture or the earlier capture did not reach that position. exits lists the apps of that earlier capture no longer listed, and dates lists up to 365 captured days, newest first.
      operationId: SerpController_serp
      parameters:
      - name: keywordId
        required: true
        in: path
        schema:
          type: string
      - name: date
        required: false
        in: query
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-08-21'
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Top search results captured for a keyword
      tags:
      - Rankings
components:
  schemas:
    Object:
      type: object
      properties: {}
  securitySchemes:
    personalApiToken:
      scheme: bearer
      bearerFormat: asob
      type: http