AsoBeast Reviews API

openapi: 3.2.0
info:
  title: asobeast Reviews 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: Reviews
paths:
  /apps/{id}/reviews:
    get:
      operationId: ReviewsController_list
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: from
        required: false
        in: query
        description: Only reviews written on or after this UTC date
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-09-15'
          type: string
      - name: replyState
        required: false
        in: query
        schema:
          type: string
          enum:
          - needs_reply
          - drafted
          - replied
          - updated
      - name: sort
        required: false
        in: query
        schema:
          default: newest
          type: string
          enum:
          - newest
          - lowest
      - name: score
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 5
          type: number
      - name: version
        required: false
        in: query
        schema:
          type: string
      - name: limit
        required: true
        in: query
        schema:
          minimum: 1
          maximum: 200
          default: 50
          allOf:
          - $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Stored reviews for an app, filtered by star, version, date and reply state
      tags:
      - Reviews
  /apps/{id}/reviews/themes:
    get:
      operationId: ReviewsController_listThemes
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: from
        required: false
        in: query
        description: Only reviews written on or after this UTC date
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-09-15'
          type: string
      - name: replyState
        required: false
        in: query
        schema:
          type: string
          enum:
          - needs_reply
          - drafted
          - replied
          - updated
      - name: sort
        required: false
        in: query
        schema:
          default: newest
          type: string
          enum:
          - newest
          - lowest
      - name: score
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 5
          type: number
      - name: version
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Complaint and praise phrases that stand out in the reviews of an app against…
      tags:
      - Reviews
  /apps/{id}/reviews/histogram:
    get:
      operationId: ReviewsController_histogram
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Ratings distribution from the latest snapshot (Google Play only)
      tags:
      - Reviews
  /apps/{id}/reviews/{reviewId}/reply:
    patch:
      operationId: ReviewRepliesController_patch
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: reviewId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewReplyPatchDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Save the reply text of a review or mark it as replied
      tags:
      - Reviews
    delete:
      operationId: ReviewRepliesController_remove
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: reviewId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      summary: Discard the reply kept for a review
      tags:
      - Reviews
  /apps/{id}/reviews/{reviewId}/reply/draft:
    post:
      operationId: ReviewRepliesController_draft
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: reviewId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewReplyDraftDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '429':
          description: The monthly AI allowance is spent; aiAllowance says when it renews
      summary: Draft the reply to a review with AI and keep it on the review
      tags:
      - Reviews
  /apps/{id}/reviews/{reviewId}/reply/post:
    post:
      description: Sends the saved reply text to App Store Connect or Google Play with the key connected in Integrations, records when and what was posted, and marks the review replied. Posting again after an edit replaces the reply on the store. Through a signed in session only. Answers 400 without saved text or over the store limit, 403 when the connected key may not reply, 404 when the store does not know the review, 409 without a usable connection, 422 when the store refuses the reply and 429 when the store asks to slow down.
      operationId: ReviewRepliesController_post
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: reviewId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Post the kept reply of a review to its store
      tags:
      - Reviews
    delete:
      description: Deletes the response posted to App Store Connect and clears the post, keeping the reply text. Through a signed in session only. Answers 404 when nothing was posted and 409 for a Google Play review, whose API offers no removal.
      operationId: ReviewRepliesController_withdraw
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: reviewId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Withdraw the reply posted to the App Store
      tags:
      - Reviews
  /apps/{id}/reviews/reply-guidelines:
    get:
      operationId: ReviewReplyGuidelinesController_read
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: The reply guidelines every AI draft follows
      tags:
      - Reviews
    put:
      operationId: ReviewReplyGuidelinesController_write
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewReplyGuidelinesDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Replace the reply guidelines of an app
      tags:
      - Reviews
  /apps/{id}/reviews/{reviewId}/translation:
    post:
      operationId: ReviewTranslationController_translate
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: reviewId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewTranslationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '429':
          description: The monthly AI allowance is spent; aiAllowance says when it renews
      summary: Translate a review with AI, or answer the translation already kept for that…
      tags:
      - Reviews
components:
  schemas:
    ReviewReplyDraftDto:
      type: object
      properties:
        tone:
          enum:
          - friendly
          - neutral
          - formal
          type: string
          default: neutral
        instructions:
          type: string
          maxLength: 500
    ReviewTranslationDto:
      type: object
      properties:
        language:
          type: string
          description: ISO 639 code of the language to translate into
          example: en
      required:
      - language
    Object:
      type: object
      properties: {}
    ReviewReplyPatchDto:
      type: object
      properties:
        text:
          type: string
          maxLength: 2000
        replied:
          type: boolean
    ReviewReplyGuidelinesDto:
      type: object
      properties:
        guidelines:
          type: string
          maxLength: 1000
      required:
      - guidelines
  securitySchemes:
    personalApiToken:
      scheme: bearer
      bearerFormat: asob
      type: http