AsoBeast Competitors API

openapi: 3.2.0
info:
  title: asobeast Competitors 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: competitors
paths:
  /apps/{id}/competitors/analysis:
    get:
      operationId: CompetitorsController_analysis
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Keyword gap and positioning analysis
      tags:
      - competitors
  /apps/{id}/competitors/discovery:
    get:
      operationId: CompetitorsController_discovery
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: days
        required: true
        in: query
        schema:
          minimum: 7
          maximum: 90
          default: 30
          allOf:
          - $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Untracked apps recurring in your keyword results
      tags:
      - competitors
  /apps/{id}/competitors/suggestions:
    get:
      description: The untracked apps that recur in this app's own keyword results over the last 30 days, with how often and how high they rank, followed by the apps the store lists as similar, each with its icon, minus the app and its tracked competitors, at most ten. On Google Play a similar app is kept only when its title and description share at least half as many of the words and phrases in this app's title and short description as the closest similar app does, most shared first. The similar apps lookup reaches the store while you wait, answers within the store deadline and spends one store lookup of the hourly allowance; when the store fails or the allowance is spent the keyword result apps are still answered and similar reads unavailable. Answers 404 for a competitor or an unknown app.
      operationId: CompetitorsController_suggest
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Suggest competitors from the keyword results and similar apps
      tags:
      - competitors
  /apps/{id}/competitors:
    post:
      operationId: CompetitorsController_add
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCompetitorDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '422':
          description: The listing is not available on iPhone, so it cannot rank in the iPhone App Store search that asobeast reads
      summary: Add a competitor app from a store URL
      tags:
      - competitors
    get:
      operationId: CompetitorsController_list
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
      summary: List competitors for an app
      tags:
      - competitors
  /apps/{id}/competitors/{competitorId}:
    delete:
      operationId: CompetitorsController_remove
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: competitorId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      summary: Remove a competitor from an app
      tags:
      - competitors
components:
  schemas:
    AddCompetitorDto:
      type: object
      properties:
        url:
          type: string
          example: https://apps.apple.com/us/app/rival-app/id1234567890
      required:
      - url
    Object:
      type: object
      properties: {}
  securitySchemes:
    personalApiToken:
      scheme: bearer
      bearerFormat: asob
      type: http