Deploy Registration

Use this endpoint with the POST method to register deploys.

Path

ENDPOINT

https://app.sleuth.io/api/1/deployments/ORG_SLUG/DEPLOYMENT_SLUG/register_deploy

The endpoint path takes 2 slugs which direct the deploy to the correct code deployment:

• ORG_SLUG: found in the URL of your Sleuth org, immediately following https://app.sleuth.io/

• DEPLOYMENT_SLUG: found in the URL, following the prefix https://app.sleuth.io/org_slug/deployments/

Authentication

Each request must contain an Authorization header including an Access Token. We recommend using an Access Token with limited scope which can only be used for deploy registration.

You can manage your org's tokens it in the Organization Settings -> Access Tokens page.

Parameters

Mandatory parameters

Name	Type	Comments
sha*	string	The git SHA of the commit to be registered as a deploy.

Optional parameters

Name	Type	Comments
environment	string	The environment to register the deploy against. If not provided Sleuth will use the default environment of the Project.
date	string	ISO 8601 deployment date and time string
branch	string	If your code deployment's target environment is mapped to a branch prefix (rather than a specific branch), you must include the deploy’s full branch name as the parameter branch.
tags	string	A single string or a comma-delimited list of tags. Defaults to tags calculated by matching paths defined in your .sleuth/TAGS file. ℹ️ Please note that tags must start with the # symbol, and can only contain: lowercase letters, numbers, and symbols - and _ .
ignore_if_duplicate	string	If the value is provided and set to true Sleuth won't return a 400 error if we see a SHA that has already been registered.
email	string	Email address of author
links	string	A key/value pair consisting of the link name and the link itself in the following format: mylink=http://my.link If you need to send multiple then send a JSON body POST where the links are a dictionary of values.
commits		A list of commits to use instead of pulling the list of commits from the code repository. See the JSON schema for more details: https://app.sleuth.io/api/1/schema/register_deploy
files		A list of files included in the deploy, used instead of pulling the list of files from the commits. See the JSON schema for more details: https://app.sleuth.io/api/1/schema/register_deploy
pull_requests		A list of pull requests to use instead of pulling the list of pull requests from the code repository. See the JSON schema for more details: https://app.sleuth.io/api/1/schema/register_deploy

Responses

Code	Comments	Response Text
200	Deploy registered successfully.	Success
400	Returned if any of the input parameters are invalid, e.g.: - sha isn't provided - branch doesn't match the configured branch - date format isn't valid - author is not a valid email - we're unable to validate if the sha exists in the remote system	The response text will indicate the nature of the error: String of message problem
401	API key not valid or the deployment is not in the specified organization	String of message problem

Examples

Make sure you replace the values surrounded by< and >with your own values.

cURL

curl -X POST \
'https://app.sleuth.io/api/1/deployments/<ORG_SLUG>/<DEPLOYMENT_SLUG>/register_deploy' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "sha": "<SHA>",
  "environment": "<ENVIRONMENT>"
}'

cURL with optional Tags

curl -X POST \
'https://app.sleuth.io/api/1/deployments/<ORG_SLUG>/<DEPLOYMENT_SLUG>/register_deploy' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "sha": "<SHA>",
  "environment": "<ENVIRONMENT>",
  "tags": [
    "#tag1",
    "#tag2",
    "#tag3"
    ]
  }'

ℹ️ Please note that tags must start with the # symbol, must be separated with commas, and cannot contain the . symbol.

PowerShell

Invoke-RestMethod -Method POST `
-Uri 'https://app.sleuth.io/api/1/deployments/<ORG_SLUG>/<DEPLOYMENT_SLUG>/register-deploy' `
-Headers @{
      'Authorization' = 'Bearer <ACCESS_TOKEN>'
      'Content-Type' = 'application/json'
} `
-Body '{
      "environment": "<ENVIRONMENT>",
      "sha": "<SHA>" 
 }'

cURL using Custom Git

curl -X POST -v \
'https://app.sleuth.io/api/1/deployments/<ORG_SLUG>/<DEPLOYMENT_SLUG>/register_deploy' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sha": "<SHA>",
    "environment": "<ENVIRONMENT>",
    "ignore_if_duplicate": "true",
    "commits": [
      {
        "revision": "<COMMIT SHA>",
        "message": "<YOUR COMMIT MESSAGE>",
        "author": {
          "name": "Jane",
          "email": "[e-mail]",
          "username": "[e-mail]"
        },
        "date": "2022-08-01T00:10:10+00:00",
        "files": [
          "/some/path/to/a/file.txt"
        ],
        "parents": [
          "<PARENT SHA>"
        ],
        "url": "http://www.commits/aaa"
      }
    ],
    "files": [
      {
        "path": "http://www.example.com/some/path.txt",
        "additions": 3,
        "deletions": 0,
        "url": "http://www.example.com"
      }
    ]
  }'