AsoBeast Store Connect API

openapi: 3.2.0
info:
  title: asobeast Store Connect 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: store-connect
paths:
  /store-connections:
    get:
      description: Every connected store console key with its status, the access its report requests were granted, and each primary app of that store with its report state and the first and last day of stored funnel rows. Never returns key material. available is false when the instance has no STORE_CONNECT_ENCRYPTION_KEY.
      operationId: StoreConnectionsController_state
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: The store consoles this workspace has connected
      tags:
      - store-connect
  /store-connections/{store}:
    put:
      description: Verifies the key with the store, seals it at rest bound to this workspace and replaces any key connected before, then queues a report sync. App Store Connect takes an issuer ID, a key ID and a .p8 private key; Google Play takes a service account JSON key and the bucket id of its Play Console reports. The store in the body must match the path. Owner only, through a signed in session. Answers 422 when the store refuses the key and 409 when the instance has store connections off.
      operationId: StoreConnectionsController_connect
      parameters:
      - name: store
        required: true
        in: path
        schema:
          type: string
          enum:
          - APP_STORE
          - GOOGLE_PLAY
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/AppStoreConnectionDto'
              - $ref: '#/components/schemas/PlayConnectionDto'
              discriminator:
                propertyName: store
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Connect a store console key
      tags:
      - store-connect
    delete:
      description: Deletes the sealed key and its report requests, even while the instance has store connections off. The funnel rows already stored stay.
      operationId: StoreConnectionsController_disconnect
      parameters:
      - name: store
        required: true
        in: path
        schema:
          type: string
          enum:
          - APP_STORE
          - GOOGLE_PLAY
      responses:
        '204':
          description: ''
      summary: Disconnect a store console
      tags:
      - store-connect
  /store-connections/{store}/verify:
    post:
      description: Asks the store whether the stored key still works. A refused key marks the connection rejected; an accepted one clears that and queues a report sync. Answers 409 when the stored key can no longer be decrypted.
      operationId: StoreConnectionsController_verify
      parameters:
      - name: store
        required: true
        in: path
        schema:
          type: string
          enum:
          - APP_STORE
          - GOOGLE_PLAY
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Verify the connected store console key again
      tags:
      - store-connect
  /store-connections/{store}/sync:
    post:
      description: Queues the download of the reports the store has published since the last sync. A sync already waiting is not queued twice. Answers 409 while the store refuses the key.
      operationId: StoreConnectionsController_sync
      parameters:
      - name: store
        required: true
        in: path
        schema:
          type: string
          enum:
          - APP_STORE
          - GOOGLE_PLAY
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Queue a report sync for the connected store console
      tags:
      - store-connect
  /store-connections/GOOGLE_PLAY/sign-in:
    post:
      description: Answers the Google consent address to send the owner to, asking for read only Cloud Storage access, with a state sealed to this owner and workspace that expires in ten minutes. Google returns to the web page /integrations/google-play. Owner only, through a signed in session. Answers 409 when the instance has store connections off or no Google OAuth client.
      operationId: PlaySignInController_start
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaySignInDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Start connecting Google Play with a Google account
      tags:
      - store-connect
  /store-connections/GOOGLE_PLAY/sign-in/complete:
    post:
      description: Redeems the code Google returned, lists the bucket with the account before anything is stored, seals the refresh token bound to this workspace, replaces any Google Play connection and queues a report sync. Answers 400 for a state of another owner, an expired state or a code Google refuses, 422 when the account was not granted Cloud Storage access or cannot read the bucket, and 409 when sign in is off or Google refuses the OAuth client of the instance.
      operationId: PlaySignInController_complete
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaySignInCompletionDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Finish connecting Google Play with a Google account
      tags:
      - store-connect
  /apps/{id}/funnel:
    get:
      description: 'Reads the rows the connected store console reported: a zero filled daily series of the requested days with the total and the search share, and the 7, 14 and 28 day windows of complete days against the period before. A day is complete once it is three days old and the store has delivered it. Answers connected false and empty series for a competitor, a store without an active connection, or an app the connected key does not report.'
      operationId: StoreFunnelController_report
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: country
        required: false
        in: query
        description: Count only the storefront of this market. Omitted means every market the console reports.
        schema:
          pattern: ^[a-z]{2}$
          example: de
          type: string
      - name: days
        required: false
        in: query
        description: Days of daily points, ending today
        schema:
          minimum: 7
          maximum: 365
          default: 90
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Store impressions, page views, downloads and conversion of an app by market and…
      tags:
      - store-connect
  /apps/{id}/keyword-fields/import:
    post:
      description: Marks the app as following App Store Connect, queues a store sync that imports the keyword field of every localization the live version serves, and answers 200 with the localizations of the app, storeImport following. The import replaces any field typed here, deletes the field and the localization of every localization the live version does not serve, and tracks its phrases in every market whose storefront reads the localization as its default localization. Deleted fields and localizations do not come back when the import stops. The fields stay imported while the App Store connection is active; stop importing hands them back editable, exactly as they were. Owner only, through a signed in session. Answers 409 when the app already follows App Store Connect or no active App Store Connect connection exists, and 400 for a Google Play or competitor app.
      operationId: KeywordFieldImportController_start
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Follow App Store Connect for the keyword fields of an app
      tags:
      - store-connect
    delete:
      description: Removes the follow mark of the app. The stored keyword fields stay exactly as the last import left them and become editable again. Owner only, through a signed in session. Answers 204, 404 when the app does not follow App Store Connect, and 400 for a Google Play or competitor app.
      operationId: KeywordFieldImportController_stop
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      summary: Stop following App Store Connect for the keyword fields
      tags:
      - store-connect
components:
  schemas:
    PlaySignInCompletionDto:
      type: object
      properties:
        code:
          type: string
          maxLength: 2048
          description: The code Google added to the redirect. Redeemed once with Google and never stored.
        state:
          type: string
          maxLength: 4096
          description: The state Google returned unchanged. Opens only for the signed in owner who started the sign in, within ten minutes.
      required:
      - code
      - state
    PlaySignInDto:
      type: object
      properties:
        bucket:
          type: string
          maxLength: 63
          example: pubsite_prod_rev_01234567890987654321
          description: The Cloud Storage bucket id shown under Download reports in Play Console. Carried through the Google sign in and stored with the connection.
      required:
      - bucket
    AppStoreConnectionDto:
      type: object
      properties:
        store:
          enum:
          - APP_STORE
          type: string
        issuerId:
          type: string
          example: 57246542-96fe-1a63-e053-0824d011072a
          description: Issuer ID from Users and Access, Integrations, Team Keys
        keyId:
          type: string
          example: 2X9R4HXF34
          description: Ten character key ID
        privateKey:
          type: string
          maxLength: 4096
          description: The whole contents of the downloaded .p8 file. Verified with Apple, sealed at rest and never returned.
      required:
      - store
      - issuerId
      - keyId
      - privateKey
    PlayConnectionDto:
      type: object
      properties:
        store:
          enum:
          - GOOGLE_PLAY
          type: string
        serviceAccountJson:
          type: string
          maxLength: 16384
          description: The whole contents of the JSON key file Google Cloud downloaded for the service account. Verified with Google, sealed at rest and never returned.
        bucket:
          type: string
          maxLength: 63
          example: pubsite_prod_rev_01234567890987654321
          description: The Cloud Storage bucket id shown under Download reports in Play Console
      required:
      - store
      - serviceAccountJson
      - bucket
  securitySchemes:
    personalApiToken:
      scheme: bearer
      bearerFormat: asob
      type: http