asoskill-com Credits API

openapi: 3.2.0
info:
  title: ASO Skill Developer Credits API
  version: 1.0.0
  description: 'Customer-facing API for App Store keyword search, autocomplete, difficulty,

    popularity, app metadata, credit balances, and credit purchases. Every successful data

    response costs one credit. Rejected requests and failed upstream calls do

    not consume a credit.


    Major versions are encoded in the URL. Existing `/v1/` operations do not

    receive intentional breaking changes; compatible additions may ship within

    v1, while breaking replacements use a new path such as `/v2/`. When

    practical, deprecated operations remain available for at least six months

    and return the RFC 9745 `Deprecation` header, a migration `Link` with

    `rel="deprecation"`, and an RFC 8594 `Sunset` header once removal is

    scheduled. See the developer guide for the complete policy.'
  contact:
    name: ASO Skill support
    email: viktor@asosuite.com
  license:
    name: Proprietary; use governed by the ASO Skill Terms
    url: https://www.asoskill.com/terms
servers:
- url: https://api.asoskill.com
  description: Production
security:
- bearerApiKey: []
tags:
- name: Credits
  description: API-key credit balance and usage
paths:
  /v1/credits:
    get:
      tags:
      - Credits
      operationId: credits
      summary: Read the current credit balance
      description: Returns the authenticated account's available credit buckets and total. This request does not cost a credit.
      responses:
        '200':
          description: Current credit balance; does not cost a credit
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountUnavailable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ApiError:
      type: object
      description: Machine-readable error details. Clients should branch on code and present message when useful; additional fields provide error-specific recovery context.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable snake_case identifier suitable for programmatic handling
          example: invalid_request
        message:
          type: string
          description: Human-readable explanation that is safe to show to the account owner
          example: The request body is invalid
        retryAfterSeconds:
          type: integer
          minimum: 1
          description: Suggested delay for a retryable failure, when applicable
      additionalProperties: true
    CreditsResponse:
      type: object
      required:
      - credits
      - topUp
      - requestId
      properties:
        credits:
          $ref: '#/components/schemas/CreditBalance'
        topUp:
          type: object
          required:
          - method
          - path
          properties:
            method:
              type: string
              const: GET
            path:
              type: string
              const: /v1/billing/packs
        requestId:
          type: string
    GatewayMessage:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Too Many Requests
    ErrorResponse:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
    CreditBalance:
      type: object
      required:
      - paid
      - promotional
      - dailyFree
      - total
      - used
      - dailyFreeResetsAt
      properties:
        paid:
          type: integer
          minimum: 0
        promotional:
          type: integer
          minimum: 0
        dailyFree:
          type: integer
          minimum: 0
        total:
          type: integer
          minimum: 0
        used:
          type: integer
          minimum: 0
        dailyFreeResetsAt:
          type: string
          format: date-time
  headers:
    RateLimitLimit:
      description: Compatibility field advertising the same maximum request rate.
      schema:
        type: integer
        example: 50
    RateLimitPolicy:
      description: API Gateway request policy for the route. This is a service-capacity hint, not a credit balance or per-account quota.
      schema:
        type: string
        example: '"default";q=50;w=1'
    RetryAfter:
      description: Number of seconds to wait before retrying. When absent, use exponential backoff with jitter.
      schema:
        type: integer
        minimum: 1
  responses:
    RateLimited:
      description: Request capacity or a rate allowance was exceeded; no credit is consumed. Respect Retry-After when present, otherwise retry with exponential backoff and jitter.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/GatewayMessage'
    AccountUnavailable:
      description: The account is unavailable or disabled; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected processing failure; any reserved credit is restored
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The bearer credential is missing, invalid, expired, or revoked; no credit is consumed
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/GatewayMessage'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: aso_live_...
      description: 'Long-lived secret created in the ASO Skill developer dashboard. Send it as `Authorization: Bearer <key>` and keep it on the server.'
    mcpOAuth:
      type: oauth2
      description: OAuth authorization code with S256 PKCE, dynamic client registration, exact MCP resource binding, refresh rotation, and revocation.
      flows:
        authorizationCode:
          authorizationUrl: https://api.asoskill.com/oauth/authorize
          tokenUrl: https://api.asoskill.com/oauth/token
          refreshUrl: https://api.asoskill.com/oauth/token
          scopes:
            data: Search, autocomplete, popularity, and app metadata tools
            credits: Read the connected account credit balance
externalDocs:
  description: Developer guide, including versioning and deprecation policy
  url: https://www.asoskill.com/developers#versioning
x-api-versioning:
  strategy: path
  currentMajorVersion: v1
  backwardCompatibleChangesWithinMajor: true
  minimumDeprecationPeriod: P6M
  policy: https://www.asoskill.com/developers#versioning