AsoBeast Annotations API

openapi: 3.2.0
info:
  title: asobeast Annotations 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: Annotations
paths:
  /apps/{id}/annotations:
    post:
      description: 'Stores a named event for one app: a label pinned to one UTC day, drawn as a vertical line on the rank history and visibility charts. market scopes the line to one storefront of the app''s store and tag groups a campaign; both are optional. Writes nothing to the store.'
      operationId: AnnotationsController_create
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotationDto'
      responses:
        '201':
          description: The created annotation
          content:
            application/json:
              schema:
                type: object
      summary: Mark an event on the app charts
      tags:
      - Annotations
    get:
      operationId: AnnotationsController_list
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The annotations of the app, oldest day first
          content:
            application/json:
              schema:
                type: object
      summary: List the event markers of an app
      tags:
      - Annotations
  /apps/{id}/annotations/{annotationId}:
    delete:
      operationId: AnnotationsController_remove
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: annotationId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      summary: Remove an event marker
      tags:
      - Annotations
components:
  schemas:
    CreateAnnotationDto:
      type: object
      properties:
        date:
          type: string
          example: '2026-10-08'
        label:
          type: string
          maxLength: 80
          example: Release 5.21.0
        market:
          type: string
          example: de
          pattern: ^[a-z]{2}$
        tag:
          type: string
          example: wave
      required:
      - date
      - label
  securitySchemes:
    personalApiToken:
      scheme: bearer
      bearerFormat: asob
      type: http