Nevercode App Previews API

openapi: 3.1.0
info:
  title: Codemagic App Previews API
  version: v3.0
  description: "\n# ℹ️ Overview\n\nWelcome to the Codemagic REST API. This API allows you to programmatically interact with [Codemagic's CI/CD](https://codemagic.io/) platform\nto manage your apps, trigger builds, access artifacts, and more.\n\n### Authentication\n\nAll API requests require authentication using a personal API token that is unique to each Codemagic user. The actions permitted by the token are determined by the user’s role within the team.\n\nYou can find your API token by navigating to **Teams > Personal Account > Integrations > Codemagic API > Show**.\n\nInclude your token in the request header:\n\n```\nx-auth-token: <your-api-token>\n```\n\n### Getting started\n\n1. Generate your API token from the Codemagic dashboard\n2. Explore the available endpoints in the sidebar\n3. Try out requests directly from this documentation\n\n### Rate limits\n\nCodemagic limits the number of API requests you can make within a specific amount of time to ensure the API remains\navailable for all users. Your personal rate limit is **5,000 requests per hour**.\n\nIf you exceed your rate limit, you will receive a `429` response, and the `ratelimit-remaining` header will be `0`.\nYou should not retry your request until after the time specified by the `ratelimit-reset` header.\n\n#### Checking the status of your rate limit\n\nYou can use the headers that are sent with each response to determine the current status of your rate limit.\n\n| **Header** | **Description** |\n| ---    | ---         |\n| ratelimit-limit | The maximum number of requests that you can make per hour. |\n| ratelimit-remaining | The number of requests remaining in the current rate limit window. |\n| ratelimit-reset | The number of seconds remaining until the current rate limit window resets. |\n\n### Help and support\n\n- Ask our [GitHub community](https://github.com/codemagic-ci-cd/codemagic-docs/discussions).\n- Our paying customers can get in touch with us via the in-app chat widget.\n  You have to be logged in to see the chat icon (note that some ad blockers may block the chat widget).\n\n---\n&copy; Nevercode Ltd. | All Rights Reserved | Codemagic is registered trademark of Nevercode Ltd. | [Terms](https://codemagic.io/terms)\n"
servers:
- url: https://codemagic.io/
  x-internal: false
security:
- api_key: []
tags:
- name: App Previews
  description: REST API endpoints for app previews.
  external_docs: null
paths:
  /api/v3/builds/{build_id}/preview:
    post:
      tags:
      - App Previews
      summary: Start an app preview
      operationId: ApiV3BuildsBuildIdPreviewStartPreview
      parameters:
      - name: build_id
        in: path
        schema:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        required: true
        deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartPreviewSchema'
        required: true
      responses:
        '201':
          description: Document created, URL follows
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPagination_api.routes.builds.schemas.StartedAppPreviewSchema_'
        '402':
          description: The maximum number of preview sessions has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredSchema'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Validation Exception
                examples:
                - status_code: 400
                  detail: Bad Request
                  extra: {}
      deprecated: false
  /api/v3/teams/{team_id}/previews:
    get:
      tags:
      - App Previews
      summary: List app previews for the team
      operationId: ApiV3TeamsTeamIdPreviewsListTeamPreviews
      parameters:
      - name: page_size
        in: query
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          description: The maximum number of results per page.
          default: 30
        description: The maximum number of results per page.
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1.0
          description: The page number of the results to fetch.
          default: 1
        description: The page number of the results to fetch.
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: team_id
        in: path
        schema:
          type: string
        required: true
        deprecated: false
      responses:
        '200':
          description: Request fulfilled, document follows
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassicPagination_api.routes.team_previews.schemas.AppPreviewSchema_'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Validation Exception
                examples:
                - status_code: 400
                  detail: Bad Request
                  extra: {}
      deprecated: false
  /api/v3/previews/{preview_id}:
    get:
      tags:
      - App Previews
      summary: Get app preview information
      operationId: ApiV3PreviewsPreviewIdGetPreviewInformation
      parameters:
      - name: preview_id
        in: path
        schema:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        required: true
        deprecated: false
      responses:
        '200':
          description: Request fulfilled, document follows
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPagination_api.routes.previews.schemas.AppPreviewSchema_'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Validation Exception
                examples:
                - status_code: 400
                  detail: Bad Request
                  extra: {}
      deprecated: false
    delete:
      tags:
      - App Previews
      summary: Stop an app preview
      operationId: ApiV3PreviewsPreviewIdStopPreview
      parameters:
      - name: preview_id
        in: path
        schema:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        required: true
        deprecated: false
      responses:
        '204':
          description: Request fulfilled, nothing follows
          headers: {}
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Validation Exception
                examples:
                - status_code: 400
                  detail: Bad Request
                  extra: {}
      deprecated: false
  /api/v3/previews/{preview_id}/share:
    post:
      tags:
      - App Previews
      summary: Share an app preview
      description: Create a public ID that can be used to retrieve app preview without authentication, see [`GET /shared-previews/{shared_preview_id}`](#/operations/SharedPreviewsSharedPreviewIdGetSharedPreview).
      operationId: ApiV3PreviewsPreviewIdShareSharePreview
      parameters:
      - name: preview_id
        in: path
        schema:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        required: true
        deprecated: false
      responses:
        '201':
          description: Document created, URL follows
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPagination_api.routes.previews.schemas.SharedAppPreviewSchema_'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Validation Exception
                examples:
                - status_code: 400
                  detail: Bad Request
                  extra: {}
      deprecated: false
  /api/v3/shared-previews/{shared_preview_id}:
    get:
      tags:
      - App Previews
      summary: Get shared app preview information
      description: Get details of a publicly shared app preview. Does not require user authentication. See [`POST /previews/{preview_id}/share`](#/operations/PreviewsPreviewIdShareSharePreview) for app preview sharing.
      operationId: ApiV3SharedPreviewsSharedPreviewIdGetSharedPreview
      parameters:
      - name: shared_preview_id
        in: path
        schema:
          type: string
        required: true
        deprecated: false
      responses:
        '200':
          description: Request fulfilled, document follows
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPagination_api.routes.shared_previews.schemas.SharedAppPreviewDetailsSchema_'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Validation Exception
                examples:
                - status_code: 400
                  detail: Bad Request
                  extra: {}
      deprecated: false
      security:
      - {}
components:
  schemas:
    StartPreviewSchema:
      properties:
        artifact_path:
          type: string
      type: object
      required:
      - artifact_path
      title: StartPreviewSchema
    PaymentRequiredSchema:
      properties:
        status_code:
          type: integer
        detail:
          type: string
        extra:
          $ref: '#/components/schemas/ExtraSchema'
      type: object
      required:
      - detail
      - extra
      - status_code
      title: PaymentRequiredSchema
    SharedAppPreviewDetailsSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        streaming_public_key:
          type: string
        expires_at:
          type: string
          format: date-time
      type: object
      required:
      - expires_at
      - id
      - streaming_public_key
      title: SharedAppPreviewDetailsSchema
    team_previews_schemas_AppPreviewSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        streaming_public_key:
          type: string
        app:
          $ref: '#/components/schemas/AppPreviewApplicationSchema'
        build:
          $ref: '#/components/schemas/team_previews_schemas_BuildSchema'
        artifact:
          $ref: '#/components/schemas/team_previews_schemas_ArtifactSchema'
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        deleted_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
      type: object
      required:
      - app
      - artifact
      - build
      - created_at
      - expires_at
      - id
      - streaming_public_key
      title: AppPreviewSchema
    StartedAppPreviewSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        expires_at:
          type: string
          format: date-time
      type: object
      required:
      - expires_at
      - id
      title: StartedAppPreviewSchema
    team_previews_schemas_ReleaseNoteSchema:
      properties:
        language:
          type: string
        text:
          type: string
      type: object
      required:
      - language
      - text
      title: ReleaseNoteSchema
    NoPagination_api.routes.shared_previews.schemas.SharedAppPreviewDetailsSchema_:
      properties:
        data:
          $ref: '#/components/schemas/SharedAppPreviewDetailsSchema'
      type: object
      required:
      - data
      title: NoPagination[SharedAppPreviewDetailsSchema]
    team_previews_schemas_BuildSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        release_notes:
          items:
            $ref: '#/components/schemas/team_previews_schemas_ReleaseNoteSchema'
          type: array
        labels:
          items:
            type: string
          type: array
      type: object
      required:
      - id
      - labels
      - release_notes
      title: BuildSchema
    NoPagination_api.routes.previews.schemas.AppPreviewSchema_:
      properties:
        data:
          $ref: '#/components/schemas/previews_schemas_AppPreviewSchema'
      type: object
      required:
      - data
      title: NoPagination[AppPreviewSchema]
    NoPagination_api.routes.previews.schemas.SharedAppPreviewSchema_:
      properties:
        data:
          $ref: '#/components/schemas/SharedAppPreviewSchema'
      type: object
      required:
      - data
      title: NoPagination[SharedAppPreviewSchema]
    NoPagination_api.routes.builds.schemas.StartedAppPreviewSchema_:
      properties:
        data:
          $ref: '#/components/schemas/StartedAppPreviewSchema'
      type: object
      required:
      - data
      title: NoPagination[StartedAppPreviewSchema]
    previews_schemas_ArtifactSchema:
      properties:
        name:
          type: string
        path:
          type: string
        version_code:
          oneOf:
          - type: string
          - type: 'null'
        version_name:
          oneOf:
          - type: string
          - type: 'null'
      type: object
      required:
      - name
      - path
      title: ArtifactSchema
    ExtraSchema:
      properties:
        limit:
          type: integer
      type: object
      required:
      - limit
      title: ExtraSchema
    SharedAppPreviewSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        shared_preview_id:
          type: string
      type: object
      required:
      - id
      - shared_preview_id
      title: SharedAppPreviewSchema
    AppPreviewApplicationSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        name:
          type: string
        icon_url:
          oneOf:
          - type: string
          - type: 'null'
      type: object
      required:
      - id
      - name
      title: AppPreviewApplicationSchema
    team_previews_schemas_ArtifactSchema:
      properties:
        name:
          type: string
        path:
          type: string
        version_code:
          oneOf:
          - type: string
          - type: 'null'
        version_name:
          oneOf:
          - type: string
          - type: 'null'
      type: object
      required:
      - name
      - path
      title: ArtifactSchema
    previews_schemas_ReleaseNoteSchema:
      properties:
        language:
          type: string
        text:
          type: string
      type: object
      required:
      - language
      - text
      title: ReleaseNoteSchema
    previews_schemas_BuildSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        release_notes:
          items:
            $ref: '#/components/schemas/previews_schemas_ReleaseNoteSchema'
          type: array
        labels:
          items:
            type: string
          type: array
      type: object
      required:
      - id
      - labels
      - release_notes
      title: BuildSchema
    previews_schemas_AppSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        name:
          type: string
        icon_url:
          oneOf:
          - type: string
          - type: 'null'
      type: object
      required:
      - id
      - name
      title: AppSchema
    previews_schemas_AppPreviewSchema:
      properties:
        id:
          type: string
          examples:
          - 60a0b1c2d3e4f56789abcdef
        streaming_public_key:
          type: string
        app:
          $ref: '#/components/schemas/previews_schemas_AppSchema'
        build:
          $ref: '#/components/schemas/previews_schemas_BuildSchema'
        artifact:
          $ref: '#/components/schemas/previews_schemas_ArtifactSchema'
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        deleted_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
      type: object
      required:
      - app
      - artifact
      - build
      - created_at
      - expires_at
      - id
      - streaming_public_key
      title: AppPreviewSchema
    ClassicPagination_api.routes.team_previews.schemas.AppPreviewSchema_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/team_previews_schemas_AppPreviewSchema'
          type: array
        page_size:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
      type: object
      required:
      - current_page
      - data
      - page_size
      - total_pages
      title: ClassicPagination[AppPreviewSchema]
  securitySchemes:
    api_key:
      type: apiKey
      name: x-auth-token
      in: header