Bitrise.io API v0.1 (Work In Progress)
GitHub

Bitrise.io API v0.1 (Work In Progress)

The API is work-in-progress

The API is work-in-progress: we will add new endpoints and possibly update the existing ones in the future.

Bitrise API endpoint documentation

Check out the Bitrise API endpoint reference documentation to see all currently available endpoints and their parameters!

API domain/host and versioning

The Bitrise API’s host is: https://api.bitrise.io/

Every endpoint except the root one is versioned, and the version have to be included in the URL right after the host.

Example: https://api.bitrise.io/v0.1/me (requires authentication)

Right now we have only one version, v0.1.

There’s no long term compatibility promise for v0.1, although we try to do our best to not to break anything unless we have to. Once we’re happy with v0.1 we’ll “freeze” it as v1.0, for which we’ll provide long term support.

Authentication

The current API supports only one type of authentication: user generated Personal Access Tokens.

Right now every API endpoint requires authentication, except the “root” URL (https://api.bitrise.io).

Acquiring a Personal Access Token

  1. Sign in on bitrise.io,
  2. Go to your Account Settings page
  3. Select the Security tab on the left side.
  4. Click the Generate new token button to create a new Personal Access Token.
  5. Save the generated token.

Availability of the generated token

The generated token is shown only once, when it’s generated! There’s no way to see the token value again! You can of course generate as many Access Tokens as you like, and delete the ones you don’t need anymore.

Authenticating with the API

To provide the required access token, you have to add a HEADER to your requests, with the key Authorization and value token THE-ACCESS-TOKEN.

An example API call with auth, using curl:

curl -H 'Authorization: token THE-ACCESS-TOKEN' https://api.bitrise.io/v0.1/me

Response

Every endpoint responds with a JSON formatted response.

Pagination

When you call an endpoint that returns a list of items, you might not get the whole list in a single response. You’ll have to iterate through the “pages” to retrieve all the items.

The response of such endpoints include a paging object, with total_item_count and page_item_limit properties. If there is a “next” page available it’ll also include a next “anchor” item. For example, the response will show the app slug of the first app on the next page.

Example

{
  "data": [ ... ],
  "paging": {
    "total_item_count": 3,
    "page_item_limit": 2,
    "next": "518e869d56f2adfd"
  }
}

The next property of the paging object

The next property of the paging object is only included if there’s at least one more page available. If there’s no next property inside paging that means that there’s no more page to retrieve.

The page_item_limit property can be set with the query parameter named limit at the GET requests, so you can specify the size of the response pages. The default and also maximum value for this parameter is 50.

Example

If you want to iterate through all the items, this is what you have to do:

  1. Call the endpoint without any pagination parameters
  2. From the response process the paging object.
  3. If the paging object includes a next item, call the exact same endpoint with an additional next= query parameter, and pass the value you got in the response as the value of the next parameter.

Example

Iterating through all your registered apps:

  1. Call https://api.bitrise.io/v0.1/me/apps.
  2. Process the items (data property)
  3. Check the paging (root) property.
  4. If there’s a next property inside paging, call the endpoint again, with the next query parameter
    • Example: https://api.bitrise.io/v0.1/me/apps?next=NEXTVALUE, where NEXTVALUE is the value of the next property you got in your previous response.
  5. Repeate this until the paging object does not include a next property, which means that the page you received was the last one.

Endpoints

The Bitrise API endpoint reference documentation lists every available endpoint and their parameters, along with the possible responses. You can also try them out!

Trying the API

You can try out any endpoint in the reference documentation itself! All you need to do is authenticate yourself and provide the required parameters. The API will return the appropriate response based on the call.

  1. Acquire a Personal Access Token.
  2. Go to the Bitrise API endpoint reference documentation.
  3. Click Authorize.

  4. Paste your Personal Access Token to the Value field

  5. Click on the endpoint you want to try it out to open its details.
  6. Fill in the required parameters.
  7. Click Execute.

The API will return: