openapi: 3.1.0
info:
  title: Apple App Store Connect Apps API
  description: Automate the tasks you perform on the Apple Developer website and in App Store Connect. The App Store Connect API is a REST API that enables the automation of actions you take in App Store Connect, including managing apps, builds, beta testers, provisioning, and more. This specification covers the Apps, Builds, and Beta Testers resource groups.
  version: 3.6.0
  contact:
    name: Apple Developer Relations
    url: https://developer.apple.com/contact/
    email: developer@apple.com
  license:
    name: Apple Developer Program License Agreement
    url: https://developer.apple.com/support/terms/apple-developer-program-license-agreement/
  termsOfService: https://developer.apple.com/terms/
  x-providerName: Apple
  x-serviceName: App Store Connect
servers:
- url: https://api.appstoreconnect.apple.com
  description: App Store Connect API Production Server
security:
- BearerAuth: []
tags:
- name: Apps
  description: Manage your apps in App Store Connect, including app metadata, pricing, availability, and app information.
  externalDocs:
    url: https://developer.apple.com/documentation/appstoreconnectapi/apps
paths:
  /v1/apps:
    get:
      operationId: listApps
      summary: List Apps
      description: Find and list apps in App Store Connect. Returns a paginated list of apps associated with your Apple Developer account.
      tags:
      - Apps
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/list-apps
      parameters:
      - name: filter[bundleId]
        in: query
        description: Filter by bundle identifier
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[id]
        in: query
        description: Filter by app resource ID
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[name]
        in: query
        description: Filter by app name
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[sku]
        in: query
        description: Filter by SKU
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[appStoreVersions.platform]
        in: query
        description: Filter by platform
        schema:
          type: array
          items:
            type: string
            enum:
            - IOS
            - MAC_OS
            - TV_OS
            - VISION_OS
        style: form
        explode: false
        example: []
      - name: filter[appStoreVersions.appStoreState]
        in: query
        description: Filter by App Store version state
        schema:
          type: array
          items:
            type: string
            enum:
            - ACCEPTED
            - DEVELOPER_REJECTED
            - DEVELOPER_REMOVED_FROM_SALE
            - IN_REVIEW
            - INVALID_BINARY
            - METADATA_REJECTED
            - PENDING_APPLE_RELEASE
            - PENDING_DEVELOPER_RELEASE
            - PREPARE_FOR_SUBMISSION
            - PREORDER_READY_FOR_SALE
            - PROCESSING_FOR_APP_STORE
            - READY_FOR_REVIEW
            - READY_FOR_SALE
            - REJECTED
            - REMOVED_FROM_SALE
            - REPLACED_WITH_NEW_VERSION
            - WAITING_FOR_EXPORT_COMPLIANCE
            - WAITING_FOR_REVIEW
        style: form
        explode: false
        example: []
      - name: sort
        in: query
        description: Sort order for the results
        schema:
          type: array
          items:
            type: string
            enum:
            - bundleId
            - -bundleId
            - name
            - -name
            - sku
            - -sku
        style: form
        explode: false
        example: []
      - name: fields[apps]
        in: query
        description: Fields to return for app resources
        schema:
          type: array
          items:
            type: string
            enum:
            - alternativeDistributionKey
            - analyticsReportRequests
            - appAvailability
            - appClips
            - appCustomProductPages
            - appEncryptionDeclarations
            - appEvents
            - appInfos
            - appPricePoints
            - appPriceSchedule
            - appStoreVersionExperimentsV2
            - appStoreVersions
            - betaAppLocalizations
            - betaAppReviewDetail
            - betaGroups
            - betaLicenseAgreement
            - betaTesters
            - builds
            - bundleId
            - ciProduct
            - contentRightsDeclaration
            - customerReviews
            - endUserLicenseAgreement
            - gameCenterDetail
            - gameCenterEnabledVersions
            - inAppPurchases
            - inAppPurchasesV2
            - isOrEverWasMadeForKids
            - marketplaceSearchDetail
            - name
            - perfPowerMetrics
            - preOrder
            - preReleaseVersions
            - primaryLocale
            - promotedPurchases
            - reviewSubmissions
            - sku
            - streamlinedPurchasingEnabled
            - subscriptionGracePeriod
            - subscriptionGroups
            - subscriptionStatusUrl
            - subscriptionStatusUrlForSandbox
            - subscriptionStatusUrlVersion
            - subscriptionStatusUrlVersionForSandbox
        style: form
        explode: false
        example: []
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of apps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppsResponse'
              examples:
                Listapps200Example:
                  summary: Default listApps 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - type: apps
                      id: abc123
                    included: []
                    links:
                      self: https://www.example.com
                      first: https://www.example.com
                      next: https://www.example.com
                    meta:
                      paging:
                        total: 10
                        limit: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/apps/{id}:
    get:
      operationId: readApp
      summary: Read App Information
      description: Get information about a specific app.
      tags:
      - Apps
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/read-app-information
      parameters:
      - $ref: '#/components/parameters/AppIdParam'
      - name: fields[apps]
        in: query
        description: Fields to return for app resources
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: include
        in: query
        description: Relationship data to include in the response
        schema:
          type: array
          items:
            type: string
            enum:
            - appClips
            - appCustomProductPages
            - appEncryptionDeclarations
            - appEvents
            - appInfos
            - appStoreVersionExperimentsV2
            - appStoreVersions
            - betaAppLocalizations
            - betaAppReviewDetail
            - betaGroups
            - betaLicenseAgreement
            - builds
            - ciProduct
            - endUserLicenseAgreement
            - gameCenterDetail
            - gameCenterEnabledVersions
            - inAppPurchases
            - inAppPurchasesV2
            - preOrder
            - preReleaseVersions
            - promotedPurchases
            - reviewSubmissions
            - subscriptionGracePeriod
            - subscriptionGroups
        style: form
        explode: false
        example: []
      responses:
        '200':
          description: Single app response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'
              examples:
                Readapp200Example:
                  summary: Default readApp 200 response
                  x-microcks-default: true
                  value:
                    data:
                      type: apps
                      id: abc123
                    included: []
                    links:
                      self: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: modifyApp
      summary: Modify an App
      description: Update app information including app-level attributes.
      tags:
      - Apps
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/modify-an-app
      parameters:
      - $ref: '#/components/parameters/AppIdParam'
      requestBody:
        description: App update request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppUpdateRequest'
            examples:
              ModifyappRequestExample:
                summary: Default modifyApp request
                x-microcks-default: true
                value:
                  data:
                    type: apps
                    id: abc123
                    attributes:
                      contentRightsDeclaration: DOES_NOT_USE_THIRD_PARTY_CONTENT
                      subscriptionStatusUrl: https://www.example.com
                      subscriptionStatusUrlForSandbox: https://www.example.com
                      subscriptionStatusUrlVersion: V1
                      subscriptionStatusUrlVersionForSandbox: V1
      responses:
        '200':
          description: Updated app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'
              examples:
                Modifyapp200Example:
                  summary: Default modifyApp 200 response
                  x-microcks-default: true
                  value:
                    data:
                      type: apps
                      id: abc123
                    included: []
                    links:
                      self: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/apps/{id}/builds:
    get:
      operationId: listAppBuilds
      summary: List All Builds of an App
      description: Get a list of builds associated with a specific app.
      tags:
      - Apps
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/list-all-builds-of-an-app
      parameters:
      - $ref: '#/components/parameters/AppIdParam'
      - name: fields[builds]
        in: query
        description: Fields to return for build resources
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of builds for the app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildsResponse'
              examples:
                Listappbuilds200Example:
                  summary: Default listAppBuilds 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - type: builds
                      id: abc123
                    included: []
                    links:
                      self: https://www.example.com
                      first: https://www.example.com
                      next: https://www.example.com
                    meta:
                      paging:
                        total: 10
                        limit: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/betaTesters/{id}/apps:
    get:
      operationId: listBetaTesterApps
      summary: List All Apps for a Beta Tester
      description: Get a list of apps that a beta tester can test.
      tags:
      - Apps
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/list-all-apps-for-a-beta-tester
      parameters:
      - $ref: '#/components/parameters/BetaTesterIdParam'
      - name: fields[apps]
        in: query
        description: Fields to return for app resources
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of apps for the beta tester
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppsResponse'
              examples:
                Listbetatesterapps200Example:
                  summary: Default listBetaTesterApps 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - type: apps
                      id: abc123
                    included: []
                    links:
                      self: https://www.example.com
                      first: https://www.example.com
                      next: https://www.example.com
                    meta:
                      paging:
                        total: 10
                        limit: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AppUpdateRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - id
          properties:
            type:
              type: string
              enum:
              - apps
            id:
              type: string
            attributes:
              type: object
              properties:
                contentRightsDeclaration:
                  type: string
                  enum:
                  - DOES_NOT_USE_THIRD_PARTY_CONTENT
                  - USES_THIRD_PARTY_CONTENT
                subscriptionStatusUrl:
                  type:
                  - string
                  - 'null'
                  format: uri
                subscriptionStatusUrlForSandbox:
                  type:
                  - string
                  - 'null'
                  format: uri
                subscriptionStatusUrlVersion:
                  type:
                  - string
                  - 'null'
                  enum:
                  - V1
                  - V2
                  - null
                subscriptionStatusUrlVersionForSandbox:
                  type:
                  - string
                  - 'null'
                  enum:
                  - V1
                  - V2
                  - null
          example: example_value
    ErrorDetail:
      type: object
      required:
      - status
      - title
      properties:
        id:
          type: string
          description: A unique identifier for this error occurrence
          example: abc123
        status:
          type: string
          description: The HTTP status code for this error
          example: example_value
        code:
          type: string
          description: A machine-readable error code
          example: example_value
        title:
          type: string
          description: A short summary of the error
          example: Example Title
        detail:
          type: string
          description: A detailed explanation of the error
          example: example_value
        source:
          type: object
          properties:
            pointer:
              type: string
              description: JSON pointer to the associated entity in the request body
            parameter:
              type: string
              description: The query parameter that caused the error
          example: example_value
    ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          example: []
    RelationshipLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
          example: https://www.example.com
        related:
          type: string
          format: uri
          example: https://www.example.com
    AppResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          $ref: '#/components/schemas/App'
        included:
          type: array
          items: {}
          example: []
        links:
          $ref: '#/components/schemas/DocumentLinks'
    PagedDocumentLinks:
      type: object
      required:
      - self
      properties:
        self:
          type: string
          format: uri
          description: The URL for the current page of results
          example: https://www.example.com
        first:
          type: string
          format: uri
          description: The URL for the first page of results
          example: https://www.example.com
        next:
          type: string
          format: uri
          description: The URL for the next page of results
          example: https://www.example.com
    PagingInformation:
      type: object
      required:
      - paging
      properties:
        paging:
          type: object
          required:
          - total
          - limit
          properties:
            total:
              type: integer
              description: Total number of resources matching the request
            limit:
              type: integer
              description: Maximum number of resources returned per page
          example: example_value
    AppsResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/App'
          example: []
        included:
          type: array
          items: {}
          example: []
        links:
          $ref: '#/components/schemas/PagedDocumentLinks'
        meta:
          $ref: '#/components/schemas/PagingInformation'
    RelationshipData:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          example: example_value
        id:
          type: string
          example: abc123
    App:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          enum:
          - apps
          example: apps
        id:
          type: string
          description: The opaque resource ID that uniquely identifies the app
          example: abc123
        attributes:
          $ref: '#/components/schemas/AppAttributes'
        relationships:
          $ref: '#/components/schemas/AppRelationships'
        links:
          $ref: '#/components/schemas/ResourceLink'
    AppRelationships:
      type: object
      properties:
        builds:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        betaGroups:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        betaTesters:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
          example: example_value
        appStoreVersions:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        preReleaseVersions:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        appInfos:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
    AppAttributes:
      type: object
      properties:
        name:
          type: string
          description: The name of the app
          example: Example Title
        bundleId:
          type: string
          description: The bundle ID of the app
          example: '500123'
        sku:
          type: string
          description: The SKU of the app
          example: example_value
        primaryLocale:
          type: string
          description: The primary locale for the app (e.g., en-US)
          example: example_value
        isOrEverWasMadeForKids:
          type: boolean
          description: Whether the app is or was made for kids
          example: true
        contentRightsDeclaration:
          type: string
          enum:
          - DOES_NOT_USE_THIRD_PARTY_CONTENT
          - USES_THIRD_PARTY_CONTENT
          description: Declaration of whether the app uses third-party content
          example: DOES_NOT_USE_THIRD_PARTY_CONTENT
        streamlinedPurchasingEnabled:
          type: boolean
          description: Whether streamlined purchasing is enabled
          example: true
        subscriptionStatusUrl:
          type:
          - string
          - 'null'
          format: uri
          description: URL for subscription status notifications
          example: https://www.example.com
        subscriptionStatusUrlForSandbox:
          type:
          - string
          - 'null'
          format: uri
          description: URL for sandbox subscription status notifications
          example: https://www.example.com
        subscriptionStatusUrlVersion:
          type:
          - string
          - 'null'
          enum:
          - V1
          - V2
          - null
          description: Version of the subscription status URL
          example: V1
        subscriptionStatusUrlVersionForSandbox:
          type:
          - string
          - 'null'
          enum:
          - V1
          - V2
          - null
          description: Version of the sandbox subscription status URL
          example: V1
    BuildAttributes:
      type: object
      properties:
        version:
          type: string
          description: The build version string (CFBundleVersion)
          example: example_value
        uploadedDate:
          type: string
          format: date-time
          description: The date and time the build was uploaded
          example: '2026-01-15T10:30:00Z'
        expirationDate:
          type: string
          format: date-time
          description: The date and time the build expires
          example: '2026-01-15T10:30:00Z'
        expired:
          type: boolean
          description: Whether the build has expired
          example: true
        minOsVersion:
          type: string
          description: The minimum OS version required
          example: example_value
        lsMinimumSystemVersion:
          type: string
          description: The minimum macOS system version
          example: example_value
        computedMinMacOsVersion:
          type: string
          description: The computed minimum macOS version
          example: example_value
        iconAssetToken:
          type: object
          description: Token for the build's icon asset
          properties:
            templateUrl:
              type: string
            width:
              type: integer
            height:
              type: integer
          example: example_value
        processingState:
          type: string
          enum:
          - PROCESSING
          - FAILED
          - INVALID
          - VALID
          description: The processing state of the build
          example: PROCESSING
        buildAudienceType:
          type: string
          enum:
          - INTERNAL_ONLY
          - APP_STORE_ELIGIBLE
          description: The audience type for the build
          example: INTERNAL_ONLY
        usesNonExemptEncryption:
          type:
          - boolean
          - 'null'
          description: Whether the build uses non-exempt encryption
          example: example_value
    ResourceLink:
      type: object
      properties:
        self:
          type: string
          format: uri
          description: The URL for the resource
          example: https://www.example.com
    BuildRelationships:
      type: object
      properties:
        app:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              $ref: '#/components/schemas/RelationshipData'
          example: example_value
        preReleaseVersion:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              $ref: '#/components/schemas/RelationshipData'
          example: example_value
        individualTesters:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        betaGroups:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        betaBuildLocalizations:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
        appEncryptionDeclaration:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              $ref: '#/components/schemas/RelationshipData'
          example: example_value
        betaAppReviewSubmission:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              $ref: '#/components/schemas/RelationshipData'
          example: example_value
        buildBetaDetail:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              $ref: '#/components/schemas/RelationshipData'
          example: example_value
        appStoreVersion:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              $ref: '#/components/schemas/RelationshipData'
          example: example_value
    Build:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          enum:
          - builds
          example: builds
        id:
          type: string
          description: The opaque resource ID that uniquely identifies the build
          example: abc123
        attributes:
          $ref: '#/components/schemas/BuildAttributes'
        relationships:
          $ref: '#/components/schemas/BuildRelationships'
        links:
          $ref: '#/components/schemas/ResourceLink'
    DocumentLinks:
      type: object
      required:
      - self
      properties:
        self:
          type: string
          format: uri
          description: The URL for the resource
          example: https://www.example.com
    BuildsResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Build'
          example: []
        included:
          type: array
          items: {}
          example: []
        links:
          $ref: '#/components/schemas/PagedDocumentLinks'
        meta:
          $ref: '#/components/schemas/PagingInformation'
  responses:
    NotFound:
      description: Not found - the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - the API key does not have permission for this request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Conflict - the request conflicts with the current state of the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - the request was invalid or malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    AppIdParam:
      name: id
      in: path
      required: true
      description: The unique identifier for the app resource
      schema:
        type: string
    BetaTesterIdParam:
      name: id
      in: path
      required: true
      description: The unique identifier for the beta tester resource
      schema:
        type: string
    LimitParam:
      name: limit
      in: query
      description: Maximum number of resources to return (maximum 200)
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: App Store Connect API uses JSON Web Tokens (JWT) for authentication. Generate a token using your API key from App Store Connect. The token must include the issuer ID, key ID, and be signed with the ES256 algorithm using your private key. Tokens expire after 20 minutes.
externalDocs:
  description: Apple App Store Connect API Documentation
  url: https://developer.apple.com/documentation/appstoreconnectapi