https://github.com/drone/drone/blob/1db7bde877325829d4dc77d9ac5b0248820e6620/server/swagger/files/swagger.yml

drone-api.adoc

Drone API

Overview

Version information

Version : 1.0.0

License information

License : Creative Commons 4.0 International
License URL : http://creativecommons.org/licenses/by/4.0/
Terms of service : null

URI scheme

Host : localhost:8080
BasePath : /api
Schemes : HTTP, HTTPS

Tags

• Builds

• Repos

• User

• Users

Consumes

• application/json

Produces

• application/json

Paths

Activates a repo

POST /repos/{owner}/{name}

Description

Activates a repository.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200		Repo
400	Unable to update the Repository record in the database	No Content
403	Unable to activate the Repository due to insufficient privileges	No Content
404	Unable to retrieve the Repository from the remote system (ie GitHub)	No Content
409	Unable to activate the Repository because it is already activate	No Content
500	Unable to activate the Repository due to an internal server error. This may indicate a problem adding hooks to the remote system (ie Github), generating SSH deployment keys, or persisting to the database.	No Content

Tags

• Repos

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 200

{
  "id": 1,
  "scm": "git",
  "owner": "octocat",
  "name": "hello-world",
  "full_name": "octocat/hello-world",
  "avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
  "link_url": "https://github.com/octocat/hello-world",
  "clone_url": "https://github.com/octocat/hello-world.git",
  "default_branch": "master",
  "timeout": 60,
  "private": false,
  "trusted": false,
  "allow_pr": true,
  "allow_push": true,
  "allow_deploys": false,
  "allow_tags": false
}

Get a repo

GET /repos/{owner}/{name}

Description

Retrieves the details of a repository.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200		Repo
404	Unable to find the repository.	No Content

Tags

• Repos

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 200

{
  "id": 1,
  "scm": "git",
  "owner": "octocat",
  "name": "hello-world",
  "full_name": "octocat/hello-world",
  "avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
  "link_url": "https://github.com/octocat/hello-world",
  "clone_url": "https://github.com/octocat/hello-world.git",
  "default_branch": "master",
  "timeout": 60,
  "private": false,
  "trusted": false,
  "allow_pr": true,
  "allow_push": true,
  "allow_deploys": false,
  "allow_tags": false
}

Delete a repo

DELETE /repos/{owner}/{name}

Description

Permanently deletes a repository. It cannot be undone.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200	Successfully deleted the Repository	No Content
400	Unable to remove post-commit hooks from the remote system (ie GitHub)	No Content
404	Unable to find the Repository in the database	No Content
500	Unable to update the Repository record in the database	No Content

Tags

• Repos

Security

Type	Name
apiKey	accessToken

Updates a repo

PATCH /repos/{owner}/{name}

Description

Updates the specified repository.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	owner required	owner of the repository	string
Body	repo required	The updated repository JSON	Repo

Responses

HTTP Code	Description	Schema
200		Repo
400	Unable to update the repository in the database.	No Content
404	Unable to find the repository.	No Content

Tags

• Repos

Security

Type	Name
apiKey	accessToken

Example HTTP request

Request body

{
  "id": 1,
  "scm": "git",
  "owner": "octocat",
  "name": "hello-world",
  "full_name": "octocat/hello-world",
  "avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
  "link_url": "https://github.com/octocat/hello-world",
  "clone_url": "https://github.com/octocat/hello-world.git",
  "default_branch": "master",
  "timeout": 60,
  "private": false,
  "trusted": false,
  "allow_pr": true,
  "allow_push": true,
  "allow_deploys": false,
  "allow_tags": false
}

Example HTTP response

Response 200

{
  "id": 1,
  "scm": "git",
  "owner": "octocat",
  "name": "hello-world",
  "full_name": "octocat/hello-world",
  "avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
  "link_url": "https://github.com/octocat/hello-world",
  "clone_url": "https://github.com/octocat/hello-world.git",
  "default_branch": "master",
  "timeout": 60,
  "private": false,
  "trusted": false,
  "allow_pr": true,
  "allow_push": true,
  "allow_deploys": false,
  "allow_tags": false
}

Get recent builds

GET /repos/{owner}/{name}/builds

Description

Returns recent builds for the repository based on name.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200	The recent builds.	< Build > array
404	Unable to find the Repository in the database	No Content

Tags

• Builds

Security

Type	Name
apiKey	accessToken

Restart a build

POST /repos/{owner}/{name}/builds/{number}

Description

Restart the a build by number.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	number required	sequential build number	integer
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200	Successfully restarted the Build.	Build
404	Unable to find the Repository or Build.	No Content
409	Cannot re-start a Build that is running.	No Content

Tags

• Builds

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 200

{
  "id": 1,
  "number": 1,
  "event": "push",
  "status": "success",
  "created_at": 1443677151,
  "enqueued_at": 1443677151,
  "started_at": 1443677151,
  "finished_at": 1443677255,
  "commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
  "branch": "master",
  "ref": "refs/heads/master",
  "remote": "https://github.com/octocat/hello-world.git",
  "message": "New line at end of file. --Signed off by Spaceghost",
  "timestamp": 1443677255,
  "author": "Spaceghost",
  "author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
  "author_email": "octocat@github.com",
  "link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
  "jobs": [
    {
      "id": 1,
      "number": 1,
      "status": "success",
      "enqueued_at": 1443677151,
      "started_at": 1443677151,
      "finished_at": 1443677255,
      "exit_code": 0,
      "environment": { "GO_VERSION": "1.4" }
    },
    {
      "id": 2,
      "number": 2,
      "status": "success",
      "enqueued_at": 1443677151,
      "started_at": 1443677151,
      "finished_at": 1443677255,
      "exit_code": 0,
      "environment": { "GO_VERSION": "1.5" }
    }
  ]
}

Get the latest build

GET /repos/{owner}/{name}/builds/{number}

Description

Returns the latest repository build.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	number required	sequential build number	integer
Path	owner required	owner of the repository	string
Query	branch optional	name of the branch	string

Responses

HTTP Code	Description	Schema
200	The build.	Build
404	Unable to find the Repository or Build	No Content

Tags

• Builds

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 200

{
  "id": 1,
  "number": 1,
  "event": "push",
  "status": "success",
  "created_at": 1443677151,
  "enqueued_at": 1443677151,
  "started_at": 1443677151,
  "finished_at": 1443677255,
  "commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
  "branch": "master",
  "ref": "refs/heads/master",
  "remote": "https://github.com/octocat/hello-world.git",
  "message": "New line at end of file. --Signed off by Spaceghost",
  "timestamp": 1443677255,
  "author": "Spaceghost",
  "author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
  "author_email": "octocat@github.com",
  "link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
  "jobs": [
    {
      "id": 1,
      "number": 1,
      "status": "success",
      "enqueued_at": 1443677151,
      "started_at": 1443677151,
      "finished_at": 1443677255,
      "exit_code": 0,
      "environment": { "GO_VERSION": "1.4" }
    },
    {
      "id": 2,
      "number": 2,
      "status": "success",
      "enqueued_at": 1443677151,
      "started_at": 1443677151,
      "finished_at": 1443677255,
      "exit_code": 0,
      "environment": { "GO_VERSION": "1.5" }
    }
  ]
}

Encrypt repo secrets

POST /repos/{owner}/{name}/encrypt

Description

Encryptes a Yaml file with secret environment variables for secure public storage.

Parameters

Type	Name	Description	Schema
Path	name required	name of the repository	string
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200	The encrypted parameters.	No Content
400	Unable to encrypt the parameters.	No Content
404	Unable to find the repository.	No Content

Tags

• Repos

Security

Type	Name
apiKey	accessToken

Get build logs

GET /repos/{owner}/{name}/logs/{number}/{job}

Description

Returns the build logs for a specific job (build step).

Parameters

Type	Name	Description	Schema
Path	job required	sequential job number	integer
Path	name required	name of the repository	string
Path	number required	sequential build number	integer
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200	The logs for the requested job.	No Content
404	Unable to find the repository, build or job.	No Content

Produces

• text/plain

Tags

• Builds

Security

Type	Name
apiKey	accessToken

Cancel a Job

DELETE /repos/{owner}/{name}/logs/{number}/{job}

Description

Cancel the a build job by number.

Parameters

Type	Name	Description	Schema
Path	job required	sequential job number	integer
Path	name required	name of the repository	string
Path	number required	sequential build number	integer
Path	owner required	owner of the repository	string

Responses

HTTP Code	Description	Schema
200	Successfully cancelled the Job	No Content
404	Unable to find the Repository or Job	No Content
409	Cannot cancel a Job that is already stopped	No Content

Tags

• Builds

Security

Type	Name
apiKey	accessToken

Gets a user

GET /user

Description

Returns the currently authenticated user.

Responses

HTTP Code	Description	Schema
200	The currently authenticated user.	User

Tags

• User

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 200

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Updates a user

PATCH /user

Description

Updates the currently authenticated user.

Parameters

Type	Name	Description	Schema
Body	user required	Updates to the user.	User

Responses

HTTP Code	Description	Schema
200	The updated user.	User
400	Unable to update the user in the database	No Content

Tags

• User

Example HTTP request

Request body

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Example HTTP response

Response 200

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Get user repos

GET /user/repos

Description

Retrieve the currently authenticated User’s Repository list

Responses

HTTP Code	Description	Schema
200		< Repo > array
400	Unable to retrieve Repository list	No Content

Tags

• User

Get all users

GET /users

Description

Returns all registered, active users in the system.

Responses

HTTP Code	Description	Schema
200	All registered users.	< User > array

Tags

• Users

Security

Type	Name
apiKey	accessToken

Create a user

POST /users/{login}

Description

Creates a new user account with the specified external login.

Parameters

Type	Name	Description	Schema
Path	login required	user login to activate	string

Responses

HTTP Code	Description	Schema
201	Returns the created user.	User
400	Error inserting User into the database	No Content

Tags

• Users

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 201

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Get a user

GET /users/{login}

Description

Returns a user with the specified login name.

Parameters

Type	Name	Description	Schema
Path	login required	user login	string

Responses

HTTP Code	Description	Schema
200	Returns the user.	User
404	Cannot find user with matching login.	No Content

Tags

• Users

Security

Type	Name
apiKey	accessToken

Example HTTP response

Response 200

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Delete a user

DELETE /users/{login}

Description

Deletes the user with the specified login name.

Parameters

Type	Name	Description	Schema
Path	login required	user login	string

Responses

HTTP Code	Description	Schema
204	Successfully deleted the User	No Content
400	Error deleting the User from the database	No Content
403	Cannot delete your own User account	No Content
404	Cannot find the User	No Content

Tags

• Users

Security

Type	Name
apiKey	accessToken

Update a user

PATCH /users/{login}

Description

Updates an existing user account.

Parameters

Type	Name	Description	Schema
Path	login required	user login	string
Body	user required	changes to the user	User

Responses

HTTP Code	Description	Schema
200	Returns the updated user.	User
400	Error updating the User in the database	No Content

Tags

• Users

Security

Type	Name
apiKey	accessToken

Example HTTP request

Request body

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Example HTTP response

Response 200

{
  "id": 1,
  "login": "octocat",
  "email": "octocat@github.com",
  "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
  "admin": false,
  "active": true
}

Definitions

Build

A build for a repository.

Name	Description	Schema
author optional	The login for the author of the commit.	string
author_avatar optional	The avatar for the author of the commit.	string
author_email optional	The email for the author of the commit.	string
branch optional	The branch the commit was pushed to.	string
commit optional	The commit for the build.	string
created_at optional	When the build request was received.	integer (int64)
deploy_to optional	Where the deployment should go.	string
enqueued_at optional	When the build was enqueued.	integer (int64)
finished_at optional	When the build was finished.	integer (int64)
id optional		integer (int64)
jobs optional	The jobs associated with this build. A build will have multiple jobs if a matrix build was used or if a rebuild was requested.	< Job > array
link_url optional	The link to view the repository. This link will point to the repository state associated with the build’s commit.	string
message optional	The commit message.	string
number optional	The build number. This number is specified within the context of the repository the build belongs to and is unique within that.	integer
ref optional	The alias for the commit.	string
refspec optional	The mapping from the local repository to a branch in the remote.	string
remote optional	The remote repository.	string
started_at optional	When the build began execution.	integer (int64)
status optional	The current status of the build.	#definitions/BuildStatus
timestamp optional	When the commit was created.	integer (int64)

BuildStatus

The status of a build.

Type : enum (success, failure, pending, started, error, killed)

Feed

A feed entry for a build.

Feed entries can be used to display information on the latest builds.

Name	Description	Schema
author optional	The login for the author of the commit.	string
author_avatar optional	The avatar for the author of the commit.	string
author_email optional	The email for the author of the commit.	string
branch optional	The branch the commit was pushed to.	string
commit optional	The commit for the build.	string
created_at optional	When the build request was received.	integer (int64)
enqueued_at optional	When the build was enqueued.	integer (int64)
finished_at optional	When the build was finished.	integer (int64)
full_name optional	The full name of the repository. This is created from the owner and name of the repository.	string
link_url optional	The link to view the repository. This link will point to the repository state associated with the build’s commit.	string
message optional	The commit message.	string
name optional	The name of the repository.	string
number optional	The build number. This number is specified within the context of the repository the build belongs to and is unique within that.	integer
owner optional	The owner of the repository.	string
ref optional	The alias for the commit.	string
refspec optional	The mapping from the local repository to a branch in the remote.	string
remote optional	The remote repository.	string
started_at optional	When the build began execution.	integer (int64)
status optional	The current status of the build.	#definitions/BuildStatus
timestamp optional	When the commit was created.	integer (int64)

Job

A single job being executed as part of a build.

Name	Description	Schema
enqueued_at optional	When the job was enqueued.	integer (int64)
environment optional	The environment that the job was run with. This is a map containing any values for matrix builds.	object
exit_code optional	The exit code for the build.	integer
finished_at optional	When the job finished execution.	integer (int64)
id optional	The unique identifier for the build.	integer (int64)
number optional	The job number. This number is specified within the context of the build the job belongs to and is unique within that.	integer
started_at optional	When the job began execution.	integer (int64)
status optional	The current status of the job.	#definitions/BuildStatus

Repo

A version control repository.

Name	Description	Schema
allow_deploys optional	Whether deployment events should trigger a build.	boolean
allow_pr optional	Whether pull requests should trigger a build.	boolean
allow_push optional	Whether push events should trigger a build.	boolean
allow_tags optional	Whether tags should trigger a build.	boolean
avatar_url optional	The url for the avatar image.	string
clone_url optional	The url used to clone the repository.	string
default_branch optional	The default branch of the repository.	string
full_name optional	The full name of the repository. This is created from the owner and name of the repository.	string
id optional	The unique identifier for the repository.	integer (int64)
link_url optional	The link to view the repository.	string
name optional	The name of the repository.	string
owner optional	The owner of the repository.	string
private optional	Whether the repository is publicly visible.	boolean
scm optional	The source control management being used. Currently this is either 'git' or 'hg' (Mercurial).	string
timeout optional	The amount of time in minutes before the build is killed.	integer
trusted optional	Whether the repository has trusted access for builds. If the repository is trusted then the host network can be used and volumes can be created.	boolean

User

The user account.

Name	Description	Schema
active optional	Whether the account is currently active.	boolean
admin optional	Whether the account has administrative priviledges.	boolean
avatar_url optional	The url for the avatar image.	string
email optional	The email address for the account.	string
id optional	The unique identifier for the account.	integer (int64)
login optional	The login name for the account.	string

Security

accessToken

Type : apiKey
Name : access_token
In : QUERY