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

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

Japanese translation unavailable

This page has not been translated into Japanese yet - we apologise for the inconvenience! If you’re interested in helping us out, feel free to translate any article in the jp folder of the DevCenter repository and open a PR!

このページは日本語への翻訳がまだ完了しておりません。ご不便をおかけして申し訳ございません! もしお手伝いできる方がいらっしゃれば、ご自由にjpフォルダの記事を日本語に訳していただき、PRを開いてください

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.

Endpoints

The endpoint reference documentation has been moved to another location:

Bitrise API endpoints

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, there’s no endpoint which you can call without including the authentication information, except the “root” URL (https://api.bitrise.io).

To acquire a Personal Access Token for your user, sign in with that user on bitrise.io, go to your Account Settings page, and select the Security tab on the left side.

Here you can manage your account’s Two Factor Authentication settings, as well as your Personal Access Tokens.

To get started with the API simply click the Generate new token button, and save the generated Personal Access Token somewhere safe.

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.

Once you have the token you can start interacting 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 which returns a list of items you always have to be prepared that 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 the endpoint will include a paging object, with total_item_count and page_item_limit properties, and if there’s a “next” page available it’ll also include a next “anchor” item.

Example:

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

_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. First call the endpoint without any pagination parameters
  2. From the response process the paging object.
  3. If the paging object includes a next item, simply 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.

That’s all.

A quick example, iterating through all of your registered apps:

  1. First call https://api.bitrise.io/v0.1/me/apps
  2. Process the items (data property)
  3. Then check the paging (root) property.
  4. If there’s a next property inside paging simply 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 endpoint reference documentation has been moved:

Bitrise API endpoints