# Bugsnag Build API
Bugsnag will automatically detect new builds of your application using version information in received error events and sessions. The build API can optionally be used to tell Bugsnag when you build a new version of your application and provide extra information about it, including:
- Details about the build (e.g. when it was built, who built it)
- Source control information (to enable source code features in Bugsnag)
If you need any help or have any comments about the API please contact <firstname.lastname@example.org>.
## Matching error events and sessions to builds
The application version details are used to identify unique builds. Each unique `appVersion` represents a different build (combined with `appVersionCode` and `appBundleVersion` on some platforms). These version numbers must match the version number configured in the notifier library.
Configuring the application version in your notifier library is strongly recommended but if you are unable to do so the `autoAssignRelease` release flag can be used. This will associate any error events and sessions subsequently received with the most recent build for the release stage (e.g. production, development).
## Updating build data
Information about existing builds can be updated by making another call using the same application version details.
Any existing fields for that build will be updated with the new values. Omitted fields will not be removed. If you want to explicitly remove a field (e.g. sensitive data was accidentally included) you can set the field to `null` to indicate that you want it to be removed.
## Source control
If source control details are provided the following functionality will be available:
- Linking to code from stack traces (for some platforms only)
- Linking to code diffs to show the difference between releases
## Build [/]
### Notify of a build [POST]
Notify Bugsnag that an application has been built.
This allows build information, such as when a build was made and who made the build, to be sent to Bugsnag so that it can be displayed against release information.
It also allows source control information to be provided to allow linking error stacktraces to the source code (for supported source control tools).
+ Request (application/json)
+ apiKey: `<YOUR-NOTIFIER-API-KEY>` (required, string)
The notifier API key of the project.
+ appVersion: `1.2.3` (required, string)
The version number of the application.
This is used to identify the particular version of the application that the build relates to.
+ appVersionCode: `1234` (number)
The [version code](https://developer.android.com/studio/publish/versioning.html) of the application (Android only).
For Android apps if no version code is provided we will associate the build information with the most recent build for the app version.
+ appBundleVersion: `1.2.3` (string)
The [bundle version/build number](https://developer.apple.com/library/content/technotes/tn2420/_index.html) of the application (iOS/macOS/tvOS only).
For iOS/macOS/tvOS apps if no bundle version is provided we will associate the build information with the most recent build for the app version.
+ builderName: `Joe Bloggs` (string)
The name of the entity that triggered the build. Could be a user, system etc.
+ metadata (object)
Key value pairs containing any custom build information that provides useful metadata about the build.
e.g. build configuration parameters, versions of dependencies, reason for the build etc.
The keys and values must be strings. Nested objects aren't supported.
"buildReason": "Releasing JIRA-1234"
+ sourceControl (Source Control)
Information about the source control of the code.
This can be used to link errors to the source code (for supported source control tools)
+ releaseStage: `production` (string)
The release stage (eg, production, staging) that is being released (if applicable).
Normally the fact that a build has been released to a release stage is detected automatically when an error event or session is received for the build.
However if you would like to manually notify Bugsnag of the build being released you can specify the stage that the build was released to.
+ autoAssignRelease: `false` (boolean)
Flag indicating whether to automatically associate this build with any new error events and sessions that are received for the `releaseStage` until a subsequent build notification is received for the release stage
If this is set to `true` and no `releaseStage` is provided the build will be applied to `production`.
Automatically assigning builds to new error events is generally discouraged as it can result events from previous builds being incorrectly recorded against a new build while builds are being rolled out.
Defaults to `false`.
"builderName": "Joe Bloggs",
+ Response 200 (application/json)
"warnings": ["Source control provider is missing and could not be inferred. Please resend using one of: [github-enterprise, github, gitlab-onpremise, gitlab, bitbucket-server, bitbucket]. Request was still processed but source control information was ignored."]
+ Response 400 (application/json)
"errors": ["Missing app version"],
## Data Structures
### Source Control
+ provider: `github` (enum)
The name of the source control provider that contains the source code for the build. If the provider can be inferred from the repository then it is not required
+ `github` - [GitHub](https://github.com)
+ `github-enterprise` - [GitHub Enterprise](https://enterprise.github.com)
+ `bitbucket`- [Bitbucket](https://www.atlassian.com/software/bitbucket/) (Git and Mercurial are supported for Bitbucket)
+ `bitbucket-server`- [Bitbucket Server (formerly Stash)](https://www.atlassian.com/software/bitbucket/server)
+ `gitlab` - [GitLab](https://gitlab.com/)
+ `gitlab-onpremise` - [GitLab CE](https://about.gitlab.com/installation/) or GitLab Enterprise
+ repository: `https://github.com/owner/repo` (required, string)
The URL of the repository containing the source code being deployed.
+ revision: `42ce59f` (required, string)
The source control SHA-1 hash for the code that has been built (short or long hash)