asoskill-com MCP API

openapi: 3.2.0
info:
  title: ASO Skill Developer MCP 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: MCP
  description: OAuth-protected Model Context Protocol endpoint for AI clients
paths:
  /mcp:
    post:
      tags:
      - MCP
      security:
      - mcpOAuth:
        - data
        - credits
      operationId: mcp
      summary: Call the hosted ASO Skill MCP server
      description: Streamable HTTP MCP endpoint for ChatGPT, Claude, and compatible clients. OAuth discovery is available through the standard protected-resource and authorization-server metadata endpoints. Individual data tools cost one credit on success; the balance tool is free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: MCP JSON-RPC request or notification
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                type: object
        '202':
          description: MCP notification accepted
        '401':
          description: OAuth connection is required or expired
          headers:
            WWW-Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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
    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'
  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'
    InternalError:
      description: Unexpected processing failure; any reserved credit is restored
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying. When absent, use exponential backoff with jitter.
      schema:
        type: integer
        minimum: 1
  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