API

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 /v4.

Our API documentation can be found at api.screwdriver.cd/v4/documentation. To see yours, go to /v4/documentation.

Using the API

With Swagger

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.

Swagger page: Swagger page

Response: Swagger response

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>

Example request: Postman response

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 an Authorization header.

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:

For more information, see the GitHub OAuth documentation.

Badges

To get an image that displays the current build statuses for a particular pipeline, you can use the URL <your_UI_URL>/pipelines/<your_pipelineId>/badge.

Build Status

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

Design

Our API was designed with three principles in mind:

  1. 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.).
  2. Resources should be REST-ful and operations should be atomic so that intent is clear and human readable.
  3. 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 /v4/swagger.json.