Drone REST API

openapi: 3.0.3
info:
  title: Drone REST 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: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token retrieved from the Drone user interface profile page.

  schemas:
    User:
      type: object
      description: Represents a Drone user account.
      properties:
        id:
          type: integer
          format: int64
        login:
          type: string
        email:
          type: string
          format: email
        avatar_url:
          type: string
          format: uri
        active:
          type: boolean
        admin:
          type: boolean
        machine:
          type: boolean
        syncing:
          type: boolean
        synced:
          type: integer
          format: int64
        created:
          type: integer
          format: int64
        updated:
          type: integer
          format: int64
        last_login:
          type: integer
          format: int64
        token:
          type: string

    UserPatch:
      type: object
      description: Patch request for a user account.
      properties:
        active:
          type: boolean
        admin:
          type: boolean
        machine:
          type: boolean
        token:
          type: string

    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

    RepoPatch:
      type: object
      description: Patch request for a repository.
      properties:
        config_path:
          type: string
        protected:
          type: boolean
        trusted:
          type: boolean
        throttle:
          type: integer
          format: int64
        timeout:
          type: integer
          format: int64
        visibility:
          type: string
          enum: [public, private, internal]
        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
        counter:
          type: integer
          format: int64

    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'

    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

    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.

    Secret:
      type: object
      description: Represents a secret variable stored in Drone.
      properties:
        namespace:
          type: string
        name:
          type: string
        data:
          type: string
        pull_request:
          type: boolean
        pull_request_push:
          type: boolean

    Cron:
      type: object
      description: Represents a cron job for a repository.
      properties:
        id:
          type: integer
          format: int64
        repo_id:
          type: integer
          format: int64
        name:
          type: string
        expr:
          type: string
          description: Cron expression (e.g. "0 0 * * *").
        next:
          type: integer
          format: int64
        prev:
          type: integer
          format: int64
        event:
          type: string
          enum: [push, tag, promote, rollback]
        branch:
          type: string
        target:
          type: string
        disabled:
          type: boolean
        created:
          type: integer
          format: int64
        updated:
          type: integer
          format: int64

    CronPatch:
      type: object
      description: Patch request for a cron job.
      properties:
        event:
          type: string
        branch:
          type: string
        target:
          type: string
        disabled:
          type: boolean

    Template:
      type: object
      description: Represents a pipeline template stored in Drone.
      properties:
        name:
          type: string
        data:
          type: string
          description: Template content (YAML/Jsonnet).

    Node:
      type: object
      description: Represents a runner/agent node registered with Drone.
      properties:
        id:
          type: integer
          format: int64
        uid:
          type: string
        provider:
          type: string
        state:
          type: string
        name:
          type: string
        image:
          type: string
        region:
          type: string
        size:
          type: string
        os:
          type: string
        arch:
          type: string
        kernel:
          type: string
        variant:
          type: string
        address:
          type: string
        capacity:
          type: integer
        filters:
          type: array
          items:
            type: string
        labels:
          type: object
          additionalProperties:
            type: string
        error:
          type: string
        paused:
          type: boolean
        protected:
          type: boolean
        created:
          type: integer
          format: int64
        updated:
          type: integer
          format: int64

    NodePatch:
      type: object
      description: Patch request for a node.
      properties:
        uid:
          type: string
        provider:
          type: string
        state:
          type: string
        image:
          type: string
        region:
          type: string
        size:
          type: string
        address:
          type: string
        capacity:
          type: integer
        filters:
          type: array
          items:
            type: string
        labels:
          type: object
          additionalProperties:
            type: string
        error:
          type: string
        paused:
          type: boolean
        protected:
          type: boolean

    Version:
      type: object
      description: System version information.
      properties:
        source:
          type: string
        version:
          type: string
        commit:
          type: string

    Error:
      type: object
      description: API error response.
      properties:
        code:
          type: integer
        message:
          type: string

  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'

paths:
  /api/user:
    get:
      operationId: getCurrentUser
      summary: Get current user
      description: Returns the currently authenticated user.
      tags: [User]
      responses:
        '200':
          description: Current user information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/user/repos:
    get:
      operationId: listUserRepos
      summary: List user repositories
      description: Returns a list of all repositories to which the user has explicit access.
      tags: [User]
      responses:
        '200':
          description: List of repositories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: syncUserRepos
      summary: Sync user repositories
      description: Triggers a sync and returns the updated list of repositories.
      tags: [User]
      responses:
        '200':
          description: Synced list of repositories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/users:
    get:
      operationId: listUsers
      summary: List all users
      description: Returns a list of all registered users. Requires admin privileges.
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: List of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      summary: Create a user
      description: Creates a new user account. Requires admin privileges.
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/users/{login}:
    parameters:
      - name: login
        in: path
        required: true
        schema:
          type: string
        description: The user login/username.
    get:
      operationId: getUser
      summary: Get a user
      description: Returns a user by their login name.
      tags: [Users]
      responses:
        '200':
          description: User information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateUser
      summary: Update a user
      description: Updates a user account. Requires admin privileges.
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPatch'
      responses:
        '200':
          description: Updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: Permanently deletes a user account. Requires admin privileges.
      tags: [Users]
      responses:
        '204':
          description: User deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/repos:
    get:
      operationId: listAllRepos
      summary: List all repositories
      description: Returns a paginated list of all repositories in the database. Requires admin privileges.
      tags: [Repos]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: List of all repositories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/repos/{namespace}/{name}:
    parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
        description: The repository owner/namespace.
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The repository name.
    get:
      operationId: getRepo
      summary: Get a repository
      description: Returns a repository by namespace and name.
      tags: [Repos]
      responses:
        '200':
          description: Repository details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: enableRepo
      summary: Enable a repository
      description: Activates (enables) a repository for CI/CD in Drone.
      tags: [Repos]
      responses:
        '200':
          description: Activated repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateRepo
      summary: Update a repository
      description: Updates repository configuration settings.
      tags: [Repos]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepoPatch'
      responses:
        '200':
          description: Updated repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: disableRepo
      summary: Disable or delete a repository
      description: Disables a repository (or permanently deletes it when remove=true is passed).
      tags: [Repos]
      parameters:
        - name: remove
          in: query
          schema:
            type: boolean
          description: Set to true to permanently delete the repository.
      responses:
        '204':
          description: Repository disabled/deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/repos/{namespace}/{name}/chown:
    parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: chownRepo
      summary: Update repository owner
      description: Transfers repository ownership to the currently authenticated user.
      tags: [Repos]
      responses:
        '200':
          description: Updated repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repo'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/repos/{namespace}/{name}/repair:
    parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: repairRepo
      summary: Repair repository hooks
      description: Repairs the repository webhook hooks with the SCM provider.
      tags: [Repos]
      responses:
        '204':
          description: Repository repaired.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /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/repos/{namespace}/{name}/secrets:
    parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: listRepoSecrets
      summary: List repository secrets
      description: Returns a list of all secrets for the specified repository.
      tags: [Secrets]
      responses:
        '200':
          description: List of secrets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRepoSecret
      summary: Create a repository secret
      description: Creates a new secret for the specified repository.
      tags: [Secrets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Secret'
  

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/drone/refs/heads/main/openapi/drone-api-openapi.yml