asoskill-com Data API

openapi: 3.2.0
info:
  title: ASO Skill Developer Data 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: Data
  description: Metered App Store keyword and app data endpoints
paths:
  /v1/search:
    post:
      tags:
      - Data
      operationId: search
      summary: Search the App Store and calculate keyword difficulty
      description: Returns ordered App Store results and a 0–100 difficulty score. Results are fresh for one hour; a stale fallback is never older than 24 hours. Optional app-detail enrichment may be omitted when Apple throttles it. A successful response costs one credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search result; costs one credit
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '409':
          $ref: '#/components/responses/CreditConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailure'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/autocomplete:
    post:
      tags:
      - Data
      operationId: autocomplete
      summary: Return App Store keyword autocomplete suggestions
      description: Returns up to ten ordered, unique keyword suggestions for one storefront and Apple platform. App, developer, and editorial navigation entities are excluded. Prefix results are fresh for 30 days and cached independently per storefront and platform. A successful response costs one credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutocompleteRequest'
      responses:
        '200':
          description: Autocomplete result; costs one credit
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '409':
          $ref: '#/components/responses/CreditConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailure'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/popularity:
    post:
      tags:
      - Data
      operationId: popularity
      summary: Return a keyword popularity score
      description: Returns a 1–100 popularity score from the best available signal. When Apple censors a low direct value, an exact normalized term appearing before the full iPhone autocomplete query can conservatively raise the result to 6–10; it never lowers a stronger score or exceeds 10. Prefix and derived evidence are cached for 30 days independently from the eight-hour base popularity cache. A long cold prefix curve may finish in the background and affect a later request. A successful response costs one credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PopularityRequest'
      responses:
        '200':
          description: Popularity result; costs one credit
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopularityResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '409':
          $ref: '#/components/responses/CreditConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailure'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/apps/lookup:
    post:
      tags:
      - Data
      operationId: lookupApps
      summary: Look up detailed App Store metadata for up to 10 apps
      description: Returns platform-specific metadata for one to ten App Store IDs. A successful response costs one credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppLookupRequest'
      responses:
        '200':
          description: App details; costs one credit for the complete request
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppLookupResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '409':
          $ref: '#/components/responses/CreditConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailure'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  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
  schemas:
    CategoryRanking:
      type: object
      required:
      - chart
      - category
      - position
      properties:
        chart:
          type: string
        category:
          type: string
        position:
          type: integer
          minimum: 1
    SearchResult:
      type: object
      required:
      - position
      - appId
      - name
      properties:
        position:
          type: integer
          minimum: 1
        appId:
          type: string
        name:
          type: string
        subtitle:
          type: string
        developer:
          type: string
        rating:
          type: number
        ratingCount:
          type: integer
          minimum: 0
        categoryRank:
          type: integer
          minimum: 1
        category:
          type: string
        url:
          type: string
          format: uri
        icon:
          type: string
          format: uri
    Storefront:
      type: string
      pattern: ^[A-Za-z]{2}$
      default: US
      description: Two-letter App Store storefront code; normalized to uppercase
    PopularityResponse:
      type: object
      required:
      - term
      - storefront
      - score
      - source
      - resolution
      - scoreVersion
      - cache
      - fetchedAt
      - requestId
      properties:
        term:
          type: string
        storefront:
          type: string
        score:
          type: integer
          minimum: 1
          maximum: 100
        source:
          type: string
          enum:
          - monthly
          - direct
          - related
          - autocomplete
          - fallback
          description: Autocomplete means a conservative low-volume estimate based on the exact term appearing before the full query; raw prefixes and censored Apple values are not exposed.
        resolution:
          type: string
          enum:
          - final
          - pending
          description: Pending means background autocomplete evidence is still being collected and the score may improve on a later request. Cache only final results with the normal freshness policy.
        scoreVersion:
          type: integer
          minimum: 1
          description: Version of the popularity resolution model used for this response.
        retryAfterSeconds:
          type: integer
          minimum: 1
          description: Suggested delay before checking a pending result again.
        cache:
          $ref: '#/components/schemas/CacheStatus'
        fetchedAt:
          type: string
          format: date-time
        requestId:
          type: string
    AutocompleteRequest:
      type: object
      required:
      - term
      additionalProperties: false
      properties:
        term:
          type: string
          minLength: 1
          maxLength: 100
        storefront:
          $ref: '#/components/schemas/Storefront'
        platform:
          $ref: '#/components/schemas/Platform'
    GatewayMessage:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Too Many Requests
    SearchRequest:
      type: object
      required:
      - term
      additionalProperties: false
      properties:
        term:
          type: string
          minLength: 1
          maxLength: 100
        storefront:
          $ref: '#/components/schemas/Storefront'
        platform:
          $ref: '#/components/schemas/Platform'
    AppDetails:
      type: object
      required:
      - appId
      - developer
      - iconUrl
      - name
      - subtitle
      - categories
      - rating
      - categoryRanking
      - currentVersionNumber
      - currentVersionReleasedAt
      - versionHistory
      - screenshots
      - description
      - paid
      properties:
        appId:
          type: string
        developer:
          type: string
        iconUrl:
          type: string
          format: uri
        name:
          type: string
        subtitle:
          type:
          - string
          - 'null'
        categories:
          type: array
          items:
            type: string
        rating:
          $ref: '#/components/schemas/AppRating'
        categoryRanking:
          oneOf:
          - $ref: '#/components/schemas/CategoryRanking'
          - type: 'null'
        currentVersionNumber:
          type: string
        currentVersionReleasedAt:
          type: string
          format: date-time
        versionHistory:
          type: array
          items:
            $ref: '#/components/schemas/VersionHistoryItem'
        screenshots:
          type: array
          items:
            type: string
            format: uri
        description:
          type: string
        paid:
          type: boolean
    AppRating:
      type: object
      required:
      - average
      - count
      - one
      - two
      - three
      - four
      - five
      properties:
        average:
          type: number
        count:
          type: integer
          minimum: 0
        one:
          type: integer
          minimum: 0
        two:
          type: integer
          minimum: 0
        three:
          type: integer
          minimum: 0
        four:
          type: integer
          minimum: 0
        five:
          type: integer
          minimum: 0
    AppLookupResponse:
      type: object
      required:
      - storefront
      - platform
      - apps
      - missingAppIds
      - cache
      - fetchedAt
      - requestId
      properties:
        storefront:
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        apps:
          type: array
          items:
            $ref: '#/components/schemas/AppDetails'
        missingAppIds:
          type: array
          items:
            type: string
        cache:
          $ref: '#/components/schemas/CacheStatus'
        fetchedAt:
          type: string
          format: date-time
        requestId:
          type: string
    VersionHistoryItem:
      type: object
      required:
      - versionDisplay
      - releaseTimestamp
      properties:
        versionDisplay:
          type: string
        releaseTimestamp:
          type: string
          format: date-time
    PopularityRequest:
      type: object
      required:
      - term
      additionalProperties: false
      properties:
        term:
          type: string
          minLength: 1
          maxLength: 100
        storefront:
          $ref: '#/components/schemas/Storefront'
    AutocompleteSuggestion:
      type: object
      required:
      - position
      - term
      additionalProperties: false
      properties:
        position:
          type: integer
          minimum: 1
          maximum: 10
        term:
          type: string
    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
    ErrorResponse:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
    AppLookupRequest:
      type: object
      required:
      - appIds
      additionalProperties: false
      properties:
        appIds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          items:
            type: string
            pattern: ^\d+$
        storefront:
          $ref: '#/components/schemas/Storefront'
        platform:
          $ref: '#/components/schemas/Platform'
    Platform:
      type: string
      enum:
      - iphone
      - ipad
      - mac
      - appletv
      - watch
      - vision
      default: iphone
    AutocompleteResponse:
      type: object
      required:
      - term
      - storefront
      - platform
      - resultCount
      - suggestions
      - cache
      - fetchedAt
      - requestId
      properties:
        term:
          type: string
        storefront:
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        resultCount:
          type: integer
          minimum: 0
          maximum: 10
        suggestions:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/AutocompleteSuggestion'
        cache:
          $ref: '#/components/schemas/CacheStatus'
        fetchedAt:
          type: string
          format: date-time
        requestId:
          type: string
    SearchResponse:
      type: object
      required:
      - term
      - storefront
      - platform
      - difficulty
      - resultCount
      - results
      - cache
      - fetchedAt
      - requestId
      properties:
        term:
          type: string
        storefront:
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        difficulty:
          type: integer
          minimum: 0
          maximum: 100
        resultCount:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        cache:
          $ref: '#/components/schemas/CacheStatus'
        fetchedAt:
          type: string
          format: date-time
        requestId:
          type: string
    CacheStatus:
      type: string
      enum:
      - hit
      - refresh
      - stale
  responses:
    InvalidRequest:
      description: The request body or parameters are invalid; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    TemporarilyUnavailable:
      description: ASO Skill or an upstream service is temporarily unavailable; any reserved credit is restored. Retry after the indicated delay when provided.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientCredits:
      description: No promotional or paid credits remain; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    CreditConflict:
      description: A concurrent credit reservation could not be completed; no credit is consumed and the request may be retried
      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'
    UpstreamFailure:
      description: An upstream App Store service failed; any reserved credit is restored
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      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'
  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