openapi: 3.0.3
info:
  title: Drone REST Builds API
  description: The Drone REST API provides programmatic access to the Drone CI/CD platform, enabling management of builds, repositories, secrets, cron jobs, templates, and user accounts. Authentication is performed using bearer tokens retrieved from the Drone user interface profile page.
  version: 1.0.0
  contact:
    name: Drone Support
    url: https://docs.drone.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://your-drone-server
  description: Your self-hosted Drone server
security:
- BearerAuth: []
tags:
- name: Builds
  description: Build creation, management, and log access.
paths:
  /api/repos/{namespace}/{name}/builds:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listBuilds
      summary: List builds
      description: Returns a list of recent builds for the specified repository.
      tags:
      - Builds
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
      - name: branch
        in: query
        schema:
          type: string
      responses:
        '200':
          description: List of builds.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBuild
      summary: Create a build
      description: Creates (triggers) a new build by branch or commit.
      tags:
      - Builds
      parameters:
      - name: branch
        in: query
        schema:
          type: string
        description: Branch to build.
      - name: commit
        in: query
        schema:
          type: string
        description: Commit SHA to build.
      responses:
        '200':
          description: Created build.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: purgeBuildHistory
      summary: Purge build history
      description: Deletes build history older than the specified build number.
      tags:
      - Builds
      parameters:
      - name: before
        in: query
        required: true
        schema:
          type: integer
        description: Delete builds with numbers less than this value.
      responses:
        '204':
          description: Build history purged.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/repos/{namespace}/{name}/builds/{build}:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    - name: build
      in: path
      required: true
      schema:
        type: integer
      description: The build number. Use "latest" to get the most recent build.
    get:
      operationId: getBuild
      summary: Get a build
      description: Returns a repository build by build number.
      tags:
      - Builds
      parameters:
      - name: branch
        in: query
        schema:
          type: string
        description: When build is "latest", filter by this branch.
      responses:
        '200':
          description: Build details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: restartBuild
      summary: Restart a build
      description: Re-starts a stopped or completed build.
      tags:
      - Builds
      responses:
        '200':
          description: Restarted build.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: cancelBuild
      summary: Cancel a build
      description: Cancels a running build.
      tags:
      - Builds
      responses:
        '204':
          description: Build cancelled.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/repos/{namespace}/{name}/builds/{build}/approve/{stage}:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    - name: build
      in: path
      required: true
      schema:
        type: integer
    - name: stage
      in: path
      required: true
      schema:
        type: integer
      description: The stage number to approve.
    post:
      operationId: approveBuild
      summary: Approve a build stage
      description: Approves a blocked build stage awaiting manual approval.
      tags:
      - Builds
      responses:
        '204':
          description: Build stage approved.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/repos/{namespace}/{name}/builds/{build}/decline/{stage}:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    - name: build
      in: path
      required: true
      schema:
        type: integer
    - name: stage
      in: path
      required: true
      schema:
        type: integer
      description: The stage number to decline.
    post:
      operationId: declineBuild
      summary: Decline a build stage
      description: Declines a blocked build stage awaiting manual approval.
      tags:
      - Builds
      responses:
        '204':
          description: Build stage declined.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/repos/{namespace}/{name}/builds/{build}/promote:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    - name: build
      in: path
      required: true
      schema:
        type: integer
    post:
      operationId: promoteBuild
      summary: Promote a build
      description: Promotes a build to a target deployment environment.
      tags:
      - Builds
      parameters:
      - name: target
        in: query
        required: true
        schema:
          type: string
        description: The target environment to promote to (e.g. "production").
      responses:
        '200':
          description: Promoted build.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/repos/{namespace}/{name}/builds/{build}/rollback:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    - name: build
      in: path
      required: true
      schema:
        type: integer
    post:
      operationId: rollbackBuild
      summary: Rollback a build
      description: Rolls back the target environment to a previous build.
      tags:
      - Builds
      parameters:
      - name: target
        in: query
        required: true
        schema:
          type: string
        description: The target environment to roll back.
      responses:
        '200':
          description: Rolled-back build.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/repos/{namespace}/{name}/builds/{build}/logs/{stage}/{step}:
    parameters:
    - name: namespace
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      schema:
        type: string
    - name: build
      in: path
      required: true
      schema:
        type: integer
    - name: stage
      in: path
      required: true
      schema:
        type: integer
    - name: step
      in: path
      required: true
      schema:
        type: integer
    get:
      operationId: getBuildLogs
      summary: Get build step logs
      description: Returns the log lines for the specified build stage step.
      tags:
      - Builds
      responses:
        '200':
          description: Log lines.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Line'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: purgeBuildLogs
      summary: Purge build step logs
      description: Deletes the log lines for the specified build stage step.
      tags:
      - Builds
      responses:
        '204':
          description: Logs purged.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/builds/incomplete:
    get:
      operationId: listIncompleteBuilds
      summary: List incomplete builds
      description: Returns a list of repositories with incomplete (running/pending) builds.
      tags:
      - Builds
      responses:
        '200':
          description: List of repositories with incomplete builds.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/builds/incomplete/v2:
    get:
      operationId: listIncompleteBuildsV2
      summary: List incomplete builds (v2)
      description: Returns a list of builds, repos and stages that are running or pending.
      tags:
      - Builds
      responses:
        '200':
          description: List of running/pending build stages with repo and build context.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Build stage with repository and build context.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Step:
      type: object
      description: Represents an individual step within a stage.
      properties:
        id:
          type: integer
          format: int64
        step_id:
          type: integer
          format: int64
        number:
          type: integer
        name:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - passing
          - failing
          - killed
          - error
          - skipped
        error:
          type: string
        errignore:
          type: boolean
        exit_code:
          type: integer
        started:
          type: integer
          format: int64
        stopped:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
        depends_on:
          type: array
          items:
            type: string
        image:
          type: string
        detached:
          type: boolean
        schema:
          type: string
    Error:
      type: object
      description: API error response.
      properties:
        code:
          type: integer
        message:
          type: string
    Line:
      type: object
      description: Represents a single line of container/step log output.
      properties:
        pos:
          type: integer
          description: Line number.
        out:
          type: string
          description: Log message.
        time:
          type: integer
          format: int64
          description: Unix timestamp of the log line.
    Build:
      type: object
      description: Represents a Drone build execution.
      properties:
        id:
          type: integer
          format: int64
        repo_id:
          type: integer
          format: int64
        trigger:
          type: string
        number:
          type: integer
          format: int64
        parent:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - pending
          - running
          - passing
          - failing
          - killed
          - error
          - skipped
          - blocked
          - declined
          - waiting_on_dependencies
        error:
          type: string
        event:
          type: string
          enum:
          - push
          - pull_request
          - tag
          - promote
          - rollback
          - cron
          - custom
        action:
          type: string
        link:
          type: string
          format: uri
        timestamp:
          type: integer
          format: int64
        title:
          type: string
        message:
          type: string
        before:
          type: string
        after:
          type: string
        ref:
          type: string
        source_repo:
          type: string
        source:
          type: string
        target:
          type: string
        author_login:
          type: string
        author_name:
          type: string
        author_email:
          type: string
          format: email
        author_avatar:
          type: string
          format: uri
        sender:
          type: string
        params:
          type: object
          additionalProperties:
            type: string
        cron:
          type: string
        deploy_to:
          type: string
        deploy_id:
          type: integer
          format: int64
        debug:
          type: boolean
        started:
          type: integer
          format: int64
        finished:
          type: integer
          format: int64
        created:
          type: integer
          format: int64
        updated:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
        stages:
          type: array
          items:
            $ref: '#/components/schemas/Stage'
    Stage:
      type: object
      description: Represents a stage of build execution.
      properties:
        id:
          type: integer
          format: int64
        build_id:
          type: integer
          format: int64
        number:
          type: integer
        name:
          type: string
        kind:
          type: string
        type:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - passing
          - failing
          - killed
          - error
          - skipped
          - blocked
          - declined
          - waiting_on_dependencies
        error:
          type: string
        errignore:
          type: boolean
        exit_code:
          type: integer
        machine:
          type: string
        os:
          type: string
        arch:
          type: string
        variant:
          type: string
        kernel:
          type: string
        limit:
          type: integer
        throttle:
          type: integer
        started:
          type: integer
          format: int64
        stopped:
          type: integer
          format: int64
        created:
          type: integer
          format: int64
        updated:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
        on_success:
          type: boolean
        on_failure:
          type: boolean
        depends_on:
          type: array
          items:
            type: string
        labels:
          type: object
          additionalProperties:
            type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
    Repo:
      type: object
      description: Represents a repository registered with Drone.
      properties:
        id:
          type: integer
          format: int64
        uid:
          type: string
        user_id:
          type: integer
          format: int64
        namespace:
          type: string
        name:
          type: string
        slug:
          type: string
        scm:
          type: string
        git_http_url:
          type: string
          format: uri
        git_ssh_url:
          type: string
        link:
          type: string
          format: uri
        default_branch:
          type: string
        private:
          type: boolean
        visibility:
          type: string
          enum:
          - public
          - private
          - internal
        active:
          type: boolean
        config_path:
          type: string
        trusted:
          type: boolean
        protected:
          type: boolean
        ignore_forks:
          type: boolean
        ignore_pull_requests:
          type: boolean
        auto_cancel_pull_requests:
          type: boolean
        auto_cancel_pushes:
          type: boolean
        auto_cancel_running:
          type: boolean
        throttle:
          type: integer
          format: int64
        timeout:
          type: integer
          format: int64
        counter:
          type: integer
          format: int64
        synced:
          type: integer
          format: int64
        created:
          type: integer
          format: int64
        updated:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
  responses:
    Unauthorized:
      description: Authentication credentials missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token retrieved from the Drone user interface profile page.