Screwdriver APIs and the data models around them are documented via Swagger. This prevents out-of-date documentation, enables clients to be auto-generated, and most importantly exposes a human-readable interface.
Version 4 is the current API, all links should be prefixed with
Our API documentation can be found at api.screwdriver.cd/v4/documentation. To see yours, go to
Using the API
Swagger documentation includes examples and editable parameters to play around with. Visit the
/v4/documentation page and use the interactive
Try it out! buttons to make calls to our API.
With a REST Client
Use a REST client like Postman to make requests against the API. You will need an authorization token. To get an authorization token, login using
/v4/auth/login and copy the token value when redirected to
/v4/auth/token. See the Authorization and Authentication section for more information.
Requests can be made to the API with headers like below:
Content-Type: application/json Authorization: Bearer <YOUR_TOKEN_HERE>
For more information and examples, check out our API documentation.
Authentication and Authorization
For Authentication we’re using JSON Web Tokens (JWTs) and Screwdriver API Tokens. JWTs need to be passed via
- To generate a JWT with OAuth, visit the
/v4/auth/loginendpoint, which will redirect you to the
- To generate a JWT with a Screwdriver API Token, make a
GETrequest to the
/v4/auth/tokenendpoint with your API token as the
Screwdriver API tokens can be managed from Screwdriver’s user settings page.
Authorization is handled by your SCM. Screwdriver uses SCM user tokens and identity to:
- identify what repositories you have read, write, and admin access to
- read allows you to view the pipeline
- write allows you to start or stop jobs
- admin allows you to create, edit, or delete pipelines
- read the repository’s
- enumerate the list of pull-requests open on your repository
- update the pull-request with the success/failure of the build
- add/remove repository web-hooks so Screwdriver can be notified on changes
For more information, see the GitHub OAuth documentation.
To get an image that displays the current build statuses for a particular pipeline, you can use the URL
For example, we display the badge above by using this code in Markdown. The
status-image URL gives you the badge image and the
status-url should be the link to your pipeline.
[![Build Status][status-image]][status-url] [status-image]: https://cd.screwdriver.cd/pipelines/1/badge [status-url]: https://cd.screwdriver.cd/pipelines/1
Our API was designed with three principles in mind:
- All interactions of user’s data should be done through the API, so that there is a consistent interface across the tools (CLI, Web UI, etc.).
- Resources should be REST-ful and operations should be atomic so that intent is clear and human readable.
- API should be versioned and self-documented, so that client code generation is possible.
Make Your Own
If you’d like to make your own Swagger documentation, check out our JSON for reference at https://api.screwdriver.cd/v4/swagger.json. To see your Swagger.json, visit