bugsnag Builds API

openapi: 3.1.0
info:
  title: Bugsnag Build Builds API
  description: The Bugsnag Build API allows you to provide information about your application builds, releases, and deployments. By notifying Bugsnag when you deploy, you can track which releases introduced new errors, view error trends across releases, and identify regressions. The API accepts build metadata including version numbers, source control information, and release stages. It integrates with CI/CD pipelines to automate release tracking.
  version: '1.0'
  contact:
    name: Bugsnag Support
    url: https://docs.bugsnag.com/api/build/
  termsOfService: https://smartbear.com/terms-of-use/
servers:
- url: https://build.bugsnag.com
  description: Bugsnag Build Server
security: []
tags:
- name: Builds
  description: Notify Bugsnag about application builds and deployments. Build notifications are used to track releases, identify regressions, and associate source control information with error data.
paths:
  /:
    post:
      operationId: createBuild
      summary: Notify Bugsnag of a new build
      description: Sends build and deployment information to Bugsnag. This allows Bugsnag to track which release introduced specific errors, display release-specific error trends, and link errors to source control commits. The payload must include a valid API key and app version. Source control information and builder name are optional but recommended for full release tracking functionality.
      tags:
      - Builds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildPayload'
      responses:
        '200':
          description: The build notification was accepted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildResponse'
        '400':
          description: The payload was malformed or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The API key is invalid or missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BuildPayload:
      type: object
      description: The build notification payload containing information about an application build or deployment.
      required:
      - apiKey
      - appVersion
      properties:
        apiKey:
          type: string
          description: The Bugsnag API key for the project. Found in project settings on the Bugsnag dashboard.
          example: c9d60ae4c7e70c4b6c4ebd3e8056d2b8
        appVersion:
          type: string
          description: The version of the application being built or deployed.
          example: 1.5.0
        appVersionCode:
          type: string
          description: The version code of the application, typically used for Android applications.
        appBundleVersion:
          type: string
          description: The bundle version of the application, typically used for iOS applications.
        releaseStage:
          type: string
          description: The release stage for this build (e.g., production, staging, development). Defaults to production if not specified.
          example: production
        builderName:
          type: string
          description: The name of the person or system that created this build. If not provided, defaults to the machine's username.
          example: CI Server
        sourceControl:
          type: object
          description: Source control information for the build, used to link errors to specific commits and repositories.
          properties:
            provider:
              type: string
              description: The source control provider name.
              enum:
              - github
              - github-enterprise
              - gitlab
              - gitlab-onpremise
              - bitbucket
              - bitbucket-server
            repository:
              type: string
              format: uri
              description: The URL of the source control repository.
              example: https://github.com/myorg/myrepo
            revision:
              type: string
              description: The source control revision or commit hash for this build.
              example: abc123def456
            diff:
              type: string
              format: uri
              description: A URL to the diff between this build and the previous one.
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata to associate with the build. This data is stored alongside the release information in the Bugsnag dashboard.
        autoAssignRelease:
          type: boolean
          description: Whether to automatically assign this build as a release. Defaults to true.
          default: true
    ErrorResponse:
      type: object
      description: An error response from the build notification endpoint.
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages describing the problem.
    BuildResponse:
      type: object
      description: The response returned when a build notification is successfully processed.
      properties:
        status:
          type: string
          description: The status of the build notification.
          example: ok
        warnings:
          type: array
          items:
            type: string
          description: Any warnings about the build notification payload.
externalDocs:
  description: Bugsnag Build API Documentation
  url: https://docs.bugsnag.com/api/build/