openapi: 3.1.0
info:
  title: Bugsnag Build Builds Comments 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: Comments
  description: Manage comments on errors. Comments allow team members to discuss and annotate specific errors.
paths:
  /projects/{project_id}/errors/{error_id}/comments:
    get:
      operationId: listErrorComments
      summary: List error comments
      description: Returns a list of comments for the specified error. Comments allow team members to discuss and annotate errors.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ErrorId'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createErrorComment
      summary: Create a comment on an error
      description: Creates a new comment on the specified error. Comments support plain text content.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ErrorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /projects/{project_id}/errors/{error_id}/comments/{comment_id}:
    get:
      operationId: getComment
      summary: Get a comment
      description: Returns the details of a specific comment on an error.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ErrorId'
      - $ref: '#/components/parameters/CommentId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: updateComment
      summary: Update a comment
      description: Updates the content of an existing comment on an error.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ErrorId'
      - $ref: '#/components/parameters/CommentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteComment
      summary: Delete a comment
      description: Permanently deletes a comment from an error.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ErrorId'
      - $ref: '#/components/parameters/CommentId'
      responses:
        '204':
          description: Comment deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CommentCreate:
      type: object
      description: Request body for creating or updating a comment.
      required:
      - message
      properties:
        message:
          type: string
          description: The text content of the comment.
    Error:
      type: object
      description: An API error response.
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages.
    User:
      type: object
      description: Represents an authenticated Bugsnag user account.
      properties:
        id:
          type: string
          description: The unique identifier of the user.
        name:
          type: string
          description: The full name of the user.
        email:
          type: string
          format: email
          description: The email address associated with the user account.
        gravatar_url:
          type: string
          format: uri
          description: The Gravatar URL for the user's profile image.
        html_url:
          type: string
          format: uri
          description: The URL to the user's Bugsnag dashboard profile.
    Comment:
      type: object
      description: Represents a comment on an error, used for team discussion and annotation.
      properties:
        id:
          type: string
          description: The unique identifier of the comment.
        error_id:
          type: string
          description: The identifier of the error this comment belongs to.
        author:
          $ref: '#/components/schemas/User'
        message:
          type: string
          description: The text content of the comment.
        created_at:
          type: string
          format: date-time
          description: The date and time the comment was created.
        updated_at:
          type: string
          format: date-time
          description: The date and time the comment was last updated.
  parameters:
    CommentId:
      name: comment_id
      in: path
      required: true
      description: The unique identifier of the comment.
      schema:
        type: string
    PerPage:
      name: per_page
      in: query
      description: The number of results to return per page. Used for pagination.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    ErrorId:
      name: error_id
      in: path
      required: true
      description: The unique identifier of the error.
      schema:
        type: string
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique identifier of the project.
      schema:
        type: string
externalDocs:
  description: Bugsnag Build API Documentation
  url: https://docs.bugsnag.com/api/build/