API v0.1 (Work In Progress)

DONE: FIX: “Content-Type” instead of “Content Type” (missing -)

Content-Type is now set to application/json; charset=utf-8 for every endpoint.

1 Like

DONE: Handle /x and /x/ the same way (trailing /) - API v0.1 (Work In Progress)

Tech Note: /x/ redirects to /x; e.g. /v0.1/ is a redirect to /v0.1

1 Like

DONE: FIX: error message response format inconsistency - API v0.1 (Work In Progress)

Fixed, every endpoint should now return with message in case of error (and a proper HTTP code, of course), instead of with error_message.

Thanks for reporting @bootstraponline! :wink:

1 Like

DONE: Build: status: return a status_text too, not just the code, as well as is_on_hold

1 Like

DONE: Include commit hash & message in build data

A post was merged into an existing topic: Bitrise Public API


  • Include tag in build data (tag)
  • Include workflow id in build data (triggered_workflow)
1 Like

DONE: Include build time, and build start & finish times in the build data.

Included times in the response:

  • triggered_at
  • started_on_worker_at
  • environment_prepare_finished_at
  • finished_at
1 Like

Thank you for adding the build time info. That’s super helpful for measuring build health. :slight_smile:

1 Like

Indeed, we have quite a few use cases for these data as well :wink:

Will push another update shortly, with “abort reason” included if the build was aborted, as well as normalizing empty infos to be null instead of empty strings (e.g. if a tag is not defined it’ll be "tag":null instead of "tag":"")


DONE: Build: Abort reason (if any)

CHANGE: undefined parameters are now returned as null, instead of a default value (e.g. an empty string). Change example: previous "tag":"" is now "tag":null when tag was not specified for the build.

One issue I’m running into when calculating build metrics. There’s no way to differentiate cancelled builds from successful builds.

I have a large mono repo on GitHub. Git changes are used to determine if the build should run or not. From the Bitrise perspective, it looks like the build completed successfully. However in reality we didn’t run the build because no changes were detected.

An API to mark the build status as cancelled would be awesome.

1 Like

I see your point, but not sure how this would work. Would this be a completely separate “state” of the build? Something like “aborted”? Or would it be enough if you could simply “abort” the build through an API call right from the build, specifying an abort reason which you can now get in the /builds query?

If you have a proposed solution feel free to create a #feature-request !

  • Abort a build

is already listed here as an upcoming API so not sure a new feature request makes sense?

It’s helpful to look at how other providers handle this. On buddybuild, they created a new endpoint for canceling a build. Canceling a build is not the same as aborting. It’s a new state of the build. This is important to filter out manual aborts via the web UI from the automatic cancellation logic that ensures we’re only building changed code in a mono repo. There’s also a hidden parameter on this endpoint which controls how the GitHub status check is reported. A cancel can be reported as either a success or failure based on the value of this parameter that’s passed to the cancel endpoint.

The way this works in a mono repo workflow is as follows:

  • New PR comes in. A bunch of jobs are triggered. Custom git logic determines which apps have changed code. If there are no code changes in an app, then the build is marked as “cancelled” and filtered out of the build metrics reporting dashboard.

On bitrise we have something similar however there’s no API to cancel builds. Instead the builds run and exit early which is considered a “successful” build. However this pollutes the build metrics reporting because successful builds that executed to completion are mixed with successful builds that exited early due to change detection.

My question was exactly whether an /abort endpoint would be enough. That is definitely planned.

Having a separate /cancel endpoint, regardless how “other providers handle this”… I’m not convinced. Or maybe it’s the same thing just with different words.

In our case we call any build which “finished early” an aborted build. Marked differently on the UI as successful or failed ones. In the API you can filter these out as these have an “aborted” status. And an API endpoint to abort a build is coming soon.

I can’t see a meaningful difference between aborting and canceling a build if done through the API, but if you have a use case where aborted vs canceled builds might be a useful distinction just let me know!

Edit: note, in our case you can specify an “abort reason” which is included in the API response of build data, so you can have as many special “abort types” as you like. I don’t think having multiple endpoints for “finishing builds early” is a good idea, because you’d slowly end up with more and more endpoints for the exact same thing, to finish a build early.

Having a separate /cancel endpoint … I’m not convinced

I agree, I’m not asking for both /cancel and /abort. We need one though, regardless of what it’s called. There are different use cases for why builds are aborted, lumping them all together isn’t helpful.

I can’t see a meaningful difference between aborting and canceling a build if done through the API,

These builds shouldn’t even be making it to bitrise. When there are no code changes, a build should not be triggered in the first place. The hack of doing git change detection is just a work around for lack of first class mono repo suppport.

if you have a use case where aborted vs canceled builds might be a useful distinction just let me know!

If we are cancelling a build because there are no code changes vs aborting a build manually on the UI, that’s important info to have.

I don’t think having multiple endpoints for “finishing builds early” is a good idea,

I’m not asking for multiple endpoints. Sorry that wasn’t clear. I’m asking for a differentation between build states. Using a magic string in “abort reason” seems like it’d work but isn’t ideal.

1 Like

Makes sense. Not sure what a better solution would be, I mean with a string which you can specify you can have as many “states” or “types” as you like, which is more flexible than just a couple of special build status codes.

I’d say you could use this “reason” as “tags” or “type”, the point will be that it’s up to you how you use it. But if you have a better idea we’re definitely open :wink:

FYI it looks like that other provider just considers everything as “cancelled” so if having a distinction here is an issue then that’s fine.

The real value is being able to mark these as aborted & green on a GitHub status check without mislabeling them as a successful build. This is not currently possible.

1 Like

Can you please clarify this a bit in a #feature-request? Would love to hear more, to see how we could help.

Bumped the priority of the /abort endpoint in the meantime.