openapi: 3.1.0
info:
  title: Bugsnag Build Builds Traces 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: Traces
  description: Send OpenTelemetry trace data to Bugsnag for performance monitoring. Spans represent individual operations and are assembled into traces that visualize request flow and latency.
paths:
  /v1/traces:
    post:
      operationId: sendTraces
      summary: Send trace data
      description: Sends OpenTelemetry span data to Bugsnag using the OTLP HTTP protocol. Accepts payloads in JSON format (application/json) or protobuf format (application/x-protobuf). Spans represent individual operations such as HTTP requests, database queries, or function calls. Bugsnag assembles spans into traces to visualize request flow and identify performance bottlenecks. The maximum payload size is 1MB, and a batch size of approximately 200 spans is recommended.
      tags:
      - Traces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportTraceServiceRequest'
          application/x-protobuf:
            schema:
              type: string
              format: binary
              description: Protobuf-encoded OTLP ExportTraceServiceRequest.
      responses:
        '200':
          description: The trace data was accepted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportTraceServiceResponse'
        '400':
          description: The payload was malformed or invalid.
        '413':
          description: The payload exceeds the 1MB maximum size limit.
        '429':
          description: Rate limit or quota exceeded. Unmanaged span quota may be exhausted for the day.
components:
  schemas:
    ExportTraceServiceRequest:
      type: object
      description: The OTLP ExportTraceServiceRequest containing resource spans. This follows the OpenTelemetry protocol specification.
      properties:
        resourceSpans:
          type: array
          description: A collection of spans from a single resource (service).
          items:
            $ref: '#/components/schemas/ResourceSpans'
    KeyValue:
      type: object
      description: A key-value pair used for attributes in the OpenTelemetry data model.
      properties:
        key:
          type: string
          description: The attribute key.
        value:
          type: object
          description: The attribute value, which can be a string, integer, double, boolean, or array.
          properties:
            stringValue:
              type: string
              description: A string value.
            intValue:
              type: string
              description: An integer value, encoded as a string.
            doubleValue:
              type: number
              description: A double-precision floating point value.
            boolValue:
              type: boolean
              description: A boolean value.
    Span:
      type: object
      description: Represents a single operation within a trace. Spans have a name, start and end time, and attributes describing the operation.
      properties:
        traceId:
          type: string
          description: The trace identifier, a 32-character hex string shared by all spans in the same trace.
        spanId:
          type: string
          description: The span identifier, a 16-character hex string unique to this span.
        parentSpanId:
          type: string
          description: The span identifier of the parent span. Empty for root spans.
        name:
          type: string
          description: A descriptive name for the operation (e.g., HTTP GET /api/users).
        kind:
          type: integer
          description: The span kind indicating the relationship between the span and its parent. 0=Unspecified, 1=Internal, 2=Server, 3=Client, 4=Producer, 5=Consumer.
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
        startTimeUnixNano:
          type: string
          description: The start time of the span in nanoseconds since Unix epoch.
        endTimeUnixNano:
          type: string
          description: The end time of the span in nanoseconds since Unix epoch.
        attributes:
          type: array
          description: Key-value attributes describing the span's operation.
          items:
            $ref: '#/components/schemas/KeyValue'
        status:
          type: object
          description: The status of the span operation.
          properties:
            code:
              type: integer
              description: The status code. 0=Unset, 1=Ok, 2=Error.
              enum:
              - 0
              - 1
              - 2
            message:
              type: string
              description: An optional status message.
        events:
          type: array
          description: Time-stamped events that occurred during the span.
          items:
            type: object
            properties:
              timeUnixNano:
                type: string
                description: The event time in nanoseconds since Unix epoch.
              name:
                type: string
                description: The event name.
              attributes:
                type: array
                description: Key-value attributes for the event.
                items:
                  $ref: '#/components/schemas/KeyValue'
    ScopeSpans:
      type: object
      description: A collection of spans from a single instrumentation scope (library or component).
      properties:
        scope:
          type: object
          description: The instrumentation scope that produced the spans.
          properties:
            name:
              type: string
              description: The name of the instrumentation scope.
            version:
              type: string
              description: The version of the instrumentation scope.
        spans:
          type: array
          description: The individual spans within this scope.
          items:
            $ref: '#/components/schemas/Span'
    ExportTraceServiceResponse:
      type: object
      description: The response to an OTLP trace export request.
      properties:
        partialSuccess:
          type: object
          description: Information about partially successful exports.
          properties:
            rejectedSpans:
              type: integer
              description: The number of spans that were rejected.
            errorMessage:
              type: string
              description: An error message if some spans were rejected.
    ResourceSpans:
      type: object
      description: A collection of spans produced by a single instrumented resource.
      properties:
        resource:
          type: object
          description: The resource producing the spans, typically identifying the service name and version.
          properties:
            attributes:
              type: array
              description: Key-value attributes describing the resource.
              items:
                $ref: '#/components/schemas/KeyValue'
        scopeSpans:
          type: array
          description: A collection of spans grouped by instrumentation scope.
          items:
            $ref: '#/components/schemas/ScopeSpans'
externalDocs:
  description: Bugsnag Build API Documentation
  url: https://docs.bugsnag.com/api/build/