asoskill-com Operations API

openapi: 3.2.0
info:
  title: ASO Skill Developer Operations 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: Operations
  description: Unauthenticated service availability
paths:
  /:
    get:
      tags:
      - Operations
      security: []
      operationId: discoverApi
      summary: Discover the public ASO Skill API resources
      description: Returns stable links to the developer guide, OpenAPI contract, llms.txt, health endpoint, authentication guidance, and public endpoint summaries. This request does not cost a credit.
      responses:
        '200':
          description: Public API discovery document
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDiscoveryResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /health:
    get:
      tags:
      - Operations
      security: []
      operationId: health
      summary: Check public API availability
      description: Returns a small, unauthenticated availability response. This request does not cost a credit.
      responses:
        '200':
          description: API Gateway and the health function are running
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '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
    HealthResponse:
      type: object
      required:
      - ok
      - service
      - version
      properties:
        ok:
          type: boolean
          const: true
        service:
          type: string
          const: aso-skill
        version:
          type: string
          const: v1
    ErrorResponse:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
    ApiDiscoveryResponse:
      type: object
      required:
      - name
      - service
      - version
      - description
      - documentation
      - openapi
      - llms
      - health
      - mcp
      - versioning
      - authentication
      - endpoints
      properties:
        name:
          type: string
          const: ASO Skill Developer API
        service:
          type: string
          const: aso-skill
        version:
          type: string
          const: v1
        description:
          type: string
        documentation:
          type: string
          format: uri
        openapi:
          type: string
          format: uri
        llms:
          type: string
          format: uri
        health:
          type: string
          format: uri
        mcp:
          type: object
          required:
          - transport
          - url
          - documentation
          - authentication
          properties:
            transport:
              type: string
              const: streamable-http
            url:
              type: string
              format: uri
            documentation:
              type: string
              format: uri
            authentication:
              type: string
              const: oauth
        versioning:
          type: object
          required:
          - current
          - strategy
          - policy
          additionalProperties: false
          properties:
            current:
              type: string
              const: v1
            strategy:
              type: string
            policy:
              type: string
              format: uri
        authentication:
          type: object
          required:
          - type
          - createApiKeyAt
          - guidance
          properties:
            type:
              type: string
              const: http-bearer
            createApiKeyAt:
              type: string
              format: uri
            guidance:
              type: string
            agentLogin:
              type: object
              required:
              - method
              - path
              - verificationUrl
              properties:
                method:
                  type: string
                  const: POST
                path:
                  type: string
                  const: /v1/auth/device
                verificationUrl:
                  type: string
                  format: uri
        endpoints:
          type: object
          required:
          - search
          - autocomplete
          - popularity
          - appLookup
          - credits
          - billingPacks
          properties:
            search:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
            autocomplete:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
            popularity:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
            appLookup:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
            credits:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
            billingPacks:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
            agentLogin:
              $ref: '#/components/schemas/ApiDiscoveryEndpoint'
    ApiDiscoveryEndpoint:
      type: object
      required:
      - method
      - path
      - creditsOnSuccess
      properties:
        method:
          type: string
          enum:
          - GET
          - POST
        path:
          type: string
        creditsOnSuccess:
          type: integer
          minimum: 0
          maximum: 1
        authenticationRequired:
          type: boolean
          default: true
  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'
    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