openapi: 3.1.0
info:
  title: Bugsnag Build Builds Notifications 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: Notifications
  description: Send error and exception notifications to Bugsnag. Each notification can contain one or more events representing individual error occurrences.
paths:
  /:
    post:
      operationId: sendErrorNotification
      summary: Send an error notification
      description: Sends one or more error events to Bugsnag for processing and display in the dashboard. Each event contains exception details, stack traces, device and application information, and optional metadata. The payload must include a valid Bugsnag API key and notifier information. This endpoint is used by all official Bugsnag SDKs to deliver error data.
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPayload'
      responses:
        '200':
          description: The notification was accepted successfully.
        '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'
        '413':
          description: The payload exceeds the maximum allowed size.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Too many requests have been sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ExceptionPayload:
      type: object
      description: Represents an exception within an error event, including the error class, message, and stack trace frames.
      required:
      - errorClass
      - stacktrace
      properties:
        errorClass:
          type: string
          description: The class or type name of the exception (e.g., TypeError, NullPointerException, RuntimeError).
        message:
          type: string
          description: The human-readable error message describing what went wrong.
        stacktrace:
          type: array
          description: The stack trace frames for this exception, ordered from the frame where the error occurred to the entry point.
          items:
            $ref: '#/components/schemas/StackFramePayload'
        type:
          type: string
          description: The type of error mechanism.
          enum:
          - android
          - browserjs
          - cocoa
          - c
          - csharp
          - go
          - java
          - nodejs
          - php
          - python
          - ruby
    StackFramePayload:
      type: object
      description: Represents a single frame in an exception's stack trace.
      required:
      - file
      - lineNumber
      - method
      properties:
        file:
          type: string
          description: The file path where the code is located.
        lineNumber:
          type: integer
          description: The line number in the file where the frame originates.
        columnNumber:
          type: integer
          description: The column number in the file.
        method:
          type: string
          description: The method or function name.
        inProject:
          type: boolean
          description: Whether this frame originates from the project's own code, as opposed to a library or framework.
        code:
          type: object
          additionalProperties:
            type: string
          description: A map of line numbers to source code lines surrounding the error location.
    BreadcrumbPayload:
      type: object
      description: Represents a breadcrumb event that occurred before the error, providing context about the user's actions and application state.
      required:
      - timestamp
      - name
      - type
      properties:
        timestamp:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the breadcrumb was recorded.
        name:
          type: string
          description: A short summary of the breadcrumb event.
          maxLength: 30
        type:
          type: string
          description: The category of breadcrumb event.
          enum:
          - navigation
          - request
          - process
          - log
          - user
          - state
          - error
          - manual
        metaData:
          type: object
          additionalProperties: true
          description: Additional metadata associated with the breadcrumb.
    NotificationPayload:
      type: object
      description: The top-level notification payload sent to the Bugsnag Error Reporting API. Contains the API key, notifier information, and one or more error events.
      required:
      - apiKey
      - notifier
      - events
      properties:
        apiKey:
          type: string
          description: The Bugsnag API key for the project. Found in project settings on the Bugsnag dashboard.
          example: c9d60ae4c7e70c4b6c4ebd3e8056d2b8
        payloadVersion:
          type: string
          description: The version of the payload format. Current version is 4.
          enum:
          - '4'
          default: '4'
        notifier:
          $ref: '#/components/schemas/Notifier'
        events:
          type: array
          description: The list of error events to report. Each event represents an individual error occurrence.
          minItems: 1
          items:
            $ref: '#/components/schemas/EventPayload'
    ErrorResponse:
      type: object
      description: An error response from the notification endpoint.
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages describing the problem.
    EventPayload:
      type: object
      description: Represents a single error event occurrence. Contains exception details, stack traces, application and device information, breadcrumbs, and custom metadata.
      required:
      - exceptions
      properties:
        exceptions:
          type: array
          description: The list of exceptions that occurred. The first exception is the most significant. Multiple exceptions can represent a causal chain.
          minItems: 1
          items:
            $ref: '#/components/schemas/ExceptionPayload'
        breadcrumbs:
          type: array
          description: A trail of events leading up to the error, useful for debugging the sequence of actions that caused the error.
          items:
            $ref: '#/components/schemas/BreadcrumbPayload'
        request:
          type: object
          description: Information about the HTTP request during which the error occurred, if applicable.
          properties:
            clientIp:
              type: string
              description: The IP address of the client making the request.
            headers:
              type: object
              additionalProperties:
                type: string
              description: The HTTP request headers.
            httpMethod:
              type: string
              description: The HTTP method used (GET, POST, etc.).
            url:
              type: string
              format: uri
              description: The URL of the request.
            referer:
              type: string
              description: The referer URL.
        threads:
          type: array
          description: Information about all running threads at the time of the error.
          items:
            $ref: '#/components/schemas/ThreadPayload'
        context:
          type: string
          description: A string representing what was happening in the application at the time of the error, such as a controller action or route name.
        groupingHash:
          type: string
          description: A custom grouping hash to override the default error grouping behavior. Events with the same grouping hash will be grouped together.
        unhandled:
          type: boolean
          description: Whether this error was unhandled (true) or caught and handled (false) by the application.
        severity:
          type: string
          enum:
          - error
          - warning
          - info
          description: The severity level of the error.
        severityReason:
          type: object
          description: Information about why the severity was set to its current value.
          properties:
            type:
              type: string
              description: The reason type for the severity assignment.
              enum:
              - unhandledException
              - handledException
              - log
              - signal
              - strictMode
              - unhandledPromiseRejection
              - userSpecifiedSeverity
              - userCallbackSetSeverity
              - handledError
              - anrError
            attributes:
              type: object
              additionalProperties:
                type: string
              description: Additional attributes about the severity reason.
        user:
          type: object
          description: Information about the user who experienced the error.
          properties:
            id:
              type: string
              description: A unique identifier for the user.
            name:
              type: string
              description: The user's display name.
            email:
              type: string
              format: email
              description: The user's email address.
        app:
          type: object
          description: Information about the application in which the error occurred.
          properties:
            id:
              type: string
              description: The application identifier.
            version:
              type: string
              description: The application version string.
            versionCode:
              type: integer
              description: The numeric version code (Android).
            bundleVersion:
              type: string
              description: The bundle version (iOS).
            releaseStage:
              type: string
              description: The release stage (e.g., production, staging, development).
            type:
              type: string
              description: The application type.
            dsymUUIDs:
              type: array
              items:
                type: string
              description: UUIDs for dSYM files used in symbolication.
            duration:
              type: integer
              description: The time in milliseconds since the application started.
            durationInForeground:
              type: integer
              description: The time in milliseconds the app has been in the foreground.
            inForeground:
              type: boolean
              description: Whether the app was in the foreground when the error occurred.
        device:
          type: object
          description: Information about the device on which the error occurred.
          properties:
            hostname:
              type: string
              description: The hostname of the device.
            id:
              type: string
              description: A unique device identifier.
            manufacturer:
              type: string
              description: The device manufacturer.
            model:
              type: string
              description: The device model.
            modelNumber:
              type: string
              description: The device model number.
            osName:
              type: string
              description: The operating system name.
            osVersion:
              type: string
              description: The operating system version.
            freeMemory:
              type: integer
              description: Free memory in bytes at the time of the error.
            totalMemory:
              type: integer
              description: Total device memory in bytes.
            freeDisk:
              type: integer
              description: Free disk space in bytes.
            browserName:
              type: string
              description: The browser name, for web applications.
            browserVersion:
              type: string
              description: The browser version.
            jailbroken:
              type: boolean
              description: Whether the device is jailbroken or rooted.
            orientation:
              type: string
              description: The device orientation at the time of the error.
              enum:
              - portrait
              - landscape
            time:
              type: string
              format: date-time
              description: The device's local time when the error occurred.
            runtimeVersions:
              type: object
              additionalProperties:
                type: string
              description: Runtime version information (e.g., node, clr, swift).
        session:
          type: object
          description: Session information for the current user session.
          properties:
            id:
              type: string
              description: The unique session identifier.
            startedAt:
              type: string
              format: date-time
              description: The date and time the session started.
            events:
              type: object
              description: Event counts for this session.
              properties:
                handled:
                  type: integer
                  description: The number of handled events in this session.
                unhandled:
                  type: integer
                  description: The number of unhandled events in this session.
        metaData:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: Custom metadata organized by tab name. Each key represents a tab that will appear on the Bugsnag dashboard, containing key-value pairs of additional debugging information.
    Notifier:
      type: object
      description: Information about the notifier library sending the error report. Used by Bugsnag to identify the source SDK and version.
      required:
      - name
      - version
      - url
      properties:
        name:
          type: string
          description: The name of the notifier library.
          example: Bugsnag Ruby
        version:
          type: string
          description: The version of the notifier library.
          example: 6.24.0
        url:
          type: string
          format: uri
          description: The URL for the notifier library's homepage or repository.
          example: https://github.com/bugsnag/bugsnag-ruby
    ThreadPayload:
      type: object
      description: Information about a thread running at the time of the error.
      properties:
        id:
          type: string
          description: The thread identifier.
        name:
          type: string
          description: The thread name.
        errorReportingThread:
          type: boolean
          description: Whether this is the thread on which the error occurred.
        stacktrace:
          type: array
          description: The stack trace of this thread at the time of the error.
          items:
            $ref: '#/components/schemas/StackFramePayload'
externalDocs:
  description: Bugsnag Build API Documentation
  url: https://docs.bugsnag.com/api/build/