Apple Builds API

openapi: 3.1.0
info:
  title: Apple App Store Connect Apps Builds 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: Builds
  description: Manage builds uploaded to App Store Connect, including build metadata, processing state, and build relationships.
  externalDocs:
    url: https://developer.apple.com/documentation/appstoreconnectapi/builds
paths:
  /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:
      - Builds
      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/builds:
    get:
      operationId: listBuilds
      summary: List Builds
      description: Find and list builds for all apps in App Store Connect. Returns a paginated list of builds.
      tags:
      - Builds
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/list-builds
      parameters:
      - name: filter[app]
        in: query
        description: Filter by app resource ID
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[id]
        in: query
        description: Filter by build resource ID
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[version]
        in: query
        description: Filter by build version string
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[expired]
        in: query
        description: Filter by expiration status
        schema:
          type: array
          items:
            type: string
            enum:
            - 'true'
            - 'false'
        style: form
        explode: false
        example: []
      - name: filter[processingState]
        in: query
        description: Filter by processing state
        schema:
          type: array
          items:
            type: string
            enum:
            - PROCESSING
            - FAILED
            - INVALID
            - VALID
        style: form
        explode: false
        example: []
      - name: filter[preReleaseVersion.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[preReleaseVersion.version]
        in: query
        description: Filter by pre-release version string
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[betaGroups]
        in: query
        description: Filter by beta group IDs
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - name: filter[usesNonExemptEncryption]
        in: query
        description: Filter by encryption usage
        schema:
          type: array
          items:
            type: string
            enum:
            - 'true'
            - 'false'
        style: form
        explode: false
        example: []
      - name: sort
        in: query
        description: Sort order for results
        schema:
          type: array
          items:
            type: string
            enum:
            - preReleaseVersion
            - -preReleaseVersion
            - uploadedDate
            - -uploadedDate
            - version
            - -version
        style: form
        explode: false
        example: []
      - name: fields[builds]
        in: query
        description: Fields to return for build resources
        schema:
          type: array
          items:
            type: string
            enum:
            - app
            - appEncryptionDeclaration
            - appStoreVersion
            - betaAppReviewSubmission
            - betaBuildLocalizations
            - betaGroups
            - buildAudienceType
            - buildBetaDetail
            - buildBundles
            - computedMinMacOsVersion
            - diagnosticSignatures
            - expirationDate
            - expired
            - iconAssetToken
            - icons
            - individualTesters
            - lsMinimumSystemVersion
            - minOsVersion
            - perfPowerMetrics
            - preReleaseVersion
            - processingState
            - uploadedDate
            - usesNonExemptEncryption
            - version
        style: form
        explode: false
        example: []
      - name: include
        in: query
        description: Relationship data to include in the response
        schema:
          type: array
          items:
            type: string
            enum:
            - app
            - appEncryptionDeclaration
            - appStoreVersion
            - betaAppReviewSubmission
            - betaBuildLocalizations
            - betaGroups
            - buildBetaDetail
            - buildBundles
            - icons
            - individualTesters
            - preReleaseVersion
        style: form
        explode: false
        example: []
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildsResponse'
              examples:
                Listbuilds200Example:
                  summary: Default listBuilds 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'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/builds/{id}:
    get:
      operationId: readBuild
      summary: Read Build Information
      description: Get information about a specific build.
      tags:
      - Builds
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/read-build-information
      parameters:
      - $ref: '#/components/parameters/BuildIdParam'
      - name: fields[builds]
        in: query
        description: Fields to return for build 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:
            - app
            - appEncryptionDeclaration
            - appStoreVersion
            - betaAppReviewSubmission
            - betaBuildLocalizations
            - betaGroups
            - buildBetaDetail
            - buildBundles
            - icons
            - individualTesters
            - preReleaseVersion
        style: form
        explode: false
        example: []
      responses:
        '200':
          description: Single build response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildResponse'
              examples:
                Readbuild200Example:
                  summary: Default readBuild 200 response
                  x-microcks-default: true
                  value:
                    data:
                      type: builds
                      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: modifyBuild
      summary: Modify a Build
      description: Expire a build or change its encryption exemption setting.
      tags:
      - Builds
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/modify-a-build
      parameters:
      - $ref: '#/components/parameters/BuildIdParam'
      requestBody:
        description: Build update request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildUpdateRequest'
            examples:
              ModifybuildRequestExample:
                summary: Default modifyBuild request
                x-microcks-default: true
                value:
                  data:
                    type: builds
                    id: abc123
                    attributes:
                      expired: true
                      usesNonExemptEncryption: true
      responses:
        '200':
          description: Updated build
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildResponse'
              examples:
                Modifybuild200Example:
                  summary: Default modifyBuild 200 response
                  x-microcks-default: true
                  value:
                    data:
                      type: builds
                      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/builds/{id}/individualTesters:
    get:
      operationId: listBuildIndividualTesters
      summary: List All Individual Testers for a Build
      description: Get a list of beta testers individually assigned to a build.
      tags:
      - Builds
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/list-all-individual-testers-for-a-build
      parameters:
      - $ref: '#/components/parameters/BuildIdParam'
      - name: fields[betaTesters]
        in: query
        description: Fields to return for beta tester resources
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: []
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of beta testers for the build
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaTestersResponse'
              examples:
                Listbuildindividualtesters200Example:
                  summary: Default listBuildIndividualTesters 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - type: betaTesters
                      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}/builds:
    get:
      operationId: listBetaTesterBuilds
      summary: List All Builds Individually Assigned to a Beta Tester
      description: Get a list of builds individually assigned to a specific beta tester.
      tags:
      - Builds
      externalDocs:
        url: https://developer.apple.com/documentation/appstoreconnectapi/list-all-builds-individually-assigned-to-a-beta-tester
      parameters:
      - $ref: '#/components/parameters/BetaTesterIdParam'
      - 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 beta tester
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildsResponse'
              examples:
                Listbetatesterbuilds200Example:
                  summary: Default listBetaTesterBuilds 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
components:
  schemas:
    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
    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
    RelationshipData:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          example: example_value
        id:
          type: string
          example: abc123
    BetaTestersResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BetaTester'
          example: []
        included:
          type: array
          items: {}
          example: []
        links:
          $ref: '#/components/schemas/PagedDocumentLinks'
        meta:
          $ref: '#/components/schemas/PagingInformation'
    BetaTesterAttributes:
      type: object
      properties:
        firstName:
          type:
          - string
          - 'null'
          description: The first name of the beta tester
          example: example_value
        lastName:
          type:
          - string
          - 'null'
          description: The last name of the beta tester
          example: example_value
        email:
          type:
          - string
          - 'null'
          format: email
          description: The email address of the beta tester
          example: user@example.com
        inviteType:
          type: string
          enum:
          - EMAIL
          - PUBLIC_LINK
          description: How the tester was invited
          example: EMAIL
        state:
          type: string
          enum:
          - NOT_INVITED
          - INVITED
          - ACCEPTED
          - INSTALLED
          - REVOKED
          description: The current state of the beta tester invitation
          example: NOT_INVITED
    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
    BuildResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          $ref: '#/components/schemas/Build'
        included:
          type: array
          items: {}
          example: []
        links:
          $ref: '#/components/schemas/DocumentLinks'
    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
    BetaTester:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          enum:
          - betaTesters
          example: betaTesters
        id:
          type: string
          description: The opaque resource ID that uniquely identifies the beta tester
          example: abc123
        attributes:
          $ref: '#/components/schemas/BetaTesterAttributes'
        relationships:
          $ref: '#/components/schemas/BetaTesterRelationships'
        links:
          $ref: '#/components/schemas/ResourceLink'
    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
    BuildUpdateRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - id
          properties:
            type:
              type: string
              enum:
              - builds
            id:
              type: string
            attributes:
              type: object
              properties:
                expired:
                  type: boolean
                  description: Set to true to expire the build
                usesNonExemptEncryption:
                  type: boolean
                  description: Whether the build uses non-exempt encryption
          example: example_value
    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'
    BetaTesterRelationships:
      type: object
      properties:
        apps:
          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
        builds:
          type: object
          properties:
            links:
              $ref: '#/components/schemas/RelationshipLinks'
            data:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipData'
          example: example_value
  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:
    BuildIdParam:
      name: id
      in: path
      required: true
      description: The unique identifier for the build resource
      schema:
        type: string
    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