GitClear Public API Beta Reference

Welcome to the reference for GitClear's Public API. This API is initially being launched to accommodate customers who need to submit details about Repo Releases and Critical Defects, but it will be trivial to extend the API to grab more types of data, or designate when important events occur in your repos.

Do you have data that you would like to access or create via the GitClear API? Email support@gitclear.com -- if you're a paying subscriber, we'll add your request to our API queue. We can usually add new API actions within two weeks.

Reference quick links

Submitting an authenticated request

To submit a request to the GitClear API, include the Bearer token that can be found after you have created an API token in your entity in "Settings" -> "API Dashboard".
GET
https://www.gitclear.com/api/v1/api_tokens
curl https://www.gitclear.com/api/v1/api_tokens \ -H "Authorization: Bearer {your_token}"
Response
{ "action_em": "action_get_resource", "response_em": "response_success", "response_detail": "Your token is ready for use 👍" }

Variable type formatting

In the GitClear API reference, we specify the type for each input after the name of the key. Below, find details on the meaning of the variable types used by the GitClear API.

Input type Description Examples
Boolean A string or JSON-native boolean
"true"
true
"false"
DateTime (String)

A string that describes, at a minimum, the date an event. Generally this input should also include a time and time zone associated with it.

While the GitClear API can parse a variety of DateTime formats, it's generally recommended to pass in an ISO 8601 date, since it's ubiquitous across most programming languages.

2022-02-01T14:40:15Z
February 1, 2022 at 8:42am CST
20-12-1990
ResourcePath (String)

A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.

You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.

alloy-dev/gitclear/omniauth-azure-activedirectory
alloy-dev
your_entity_slug/your_organization_slug/your_repo_slug
SHA (string) A 40-character checksum hash used to uniquely identify a git commit, also known as the "SHA-1 hash"
114edf26fb7fb3064092200591bb84fb7c464f07
2c823f9d52ef900f4228e9881d9c04846d6434db

Critical Defects

The Critical Defect API endpoints allows you to record when a Critical Defect occurs or is fixed. You generate the the key that we'll use to refer to the defect, so it can be a Jira issue like "BANANA-123" or it could be generated from scripts that monitor Devops infrastructure.

It's not uncommon that one discovers a Critical Defect before knowing which repo was responsible for it. This is why we allow a Critical Defect to be created with an Entity or an Organization as the resource. A Critical Defect can only be designated as "fixed" (by submitting fix_released_at or fix_released_sha) in a call that specifies a repo as the resource_path param (not an organization or entity).

It is expected that sometimes the team will release a fix for a defect, but the fix will be insufficient to completely eliminate the problem. For these cases, you can continue to make API calls that mark additional commits, times, or repos where the Critical Defect has another fix released. We will consider the defect "resolved" at the latest time a fix has been marked released across all repos.

Endpoints
POST
https://www.gitclear.com/api/v1/critical_defects

Create or Update a Critical Defect

This API endpoint will ensure that a Critical Defect has been recorded, and designate when a fix is released for it.

Parameters

required
String

A customer-provided alphanumeric identifier used to subsequently refer to this defect

required
ResourcePath (String)

A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.

You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.

alloy-dev/gitclear/omniauth-azure-activedirectory
DateTime (String)

A datetime string providing the time at which the defect initially occurred. Required for the Critical Defect to be created.

Boolean

Mark the defect as occurring upon receiving the API call. This param can act as a simpler substitute for the 'detected_at' param

String

Title or description of the defect, for postmortem review

DateTime (String)

A datetime string providing the time at which a fix was released for the defect

Boolean

Mark the defect as having a fix released upon receiving the API call. This param can act as a simpler substitute for the 'fix_released_at' param

SHA (String)

The sha of the commit that deployed the fix for the defect. The authorship stamp of this commit will be used as the release time if 'fix_released_at' and 'fix_released_now' are not given

Integer

A numeric value the customer can use to record the severity of the defect (i.e., for later correlation analysis)

POST
https://www.gitclear.com/api/v1/critical_defects
curl https://www.gitclear.com/api/v1/critical_defects \ -H "Authorization: Bearer {your token}" \ -d detected_at="Jan 1, 2021 at 5:40pm PST" \ -d defect_key="JIRA-123" \ -d description="Site outage for 15 minutes" \ -d fix_released_at="Jan 2, 2021 8:35am EST" \ -d resource_path="{your resource path}" \ -d severity=2 \ -X POST
Response
{ "action_em": "action_defect_created", "response_em": "response_success", "response_detail": "Successfully ensured creation of defect release at Jan 1, 2021 5:40pm", }

Releases

Designating a release allows us to GitClear to indicate when tickets or commits have been deployed to production. Each release will ultimately be associated with a commit that immediately precedes the release. This is designated to be the "release commit" for the purposes of comparing what changed from release to release.
Endpoints
POST
https://www.gitclear.com/api/v1/releases

Create a Repo Release

This API endpoint will ensure that a Repo Release has been recorded.

Parameters

required
ResourcePath (String)

A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.

You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.

alloy-dev/gitclear/omniauth-azure-activedirectory
SHA (String)

Alias of 'release_sha', enabling Heroku users to send an HTTP post hook without renaming a parameter

String

An optional name of the release

v2.3 beta
DateTime (String)

A datetime string providing the time at which the release occurred. This parameter is required unless 'release_sha', 'head_long', or 'release_now' are given

Boolean

Mark the release as occurring upon receiving of the API call. This param can act as a simpler substitute for the 'released_at' param

SHA (String)

The sha of the commit that made the release. When present, this must be a commit that occurred within the repo specified via 'resource_path'.

The authorship timestamp of this commit will be used as the released_at time if a released_at is not provided.

POST
https://www.gitclear.com/api/v1/releases
curl https://www.gitclear.com/api/v1/releases \ -H "Authorization: Bearer {your token}" \ -d name="v3.1 beta" -d released_at='May 25, 2021 at 4:20pm' -d release_sha='541a8b28d08405aa961f9de1d7c8fcd5c3da3218' -d resource_path="{your repo path}" \ -X POST
Response
{ "action_em": "action_release_created", "response_em": "response_success", "response_detail": "Release ensured to exist at May 25 at 4:20 pm in 'alloy/gitclear/libinput'", }