Sleuth API

‌The Sleuth REST API provides methods that enables users to:‌

Sleuth's main public API is built using GraphQL. It's the same API we use internally for developing our applications.

If you're new to GraphQL, Apollo has resources for beginners. The official documentation is another good starting point.

NOTE: the GraphQL API is still under heavy development and is subject to change

Sleuth's GraphQL endpoint is:

https://app.sleuth.io/graphql

We expose the GraphiQL client so you can explore and query the API.

‌Authentication‌

The Sleuth REST API requires authentication using the API key from your Sleuth organization.

Organization and Deployment Slugs‌

Note that the organization and deployment slugs are not the semantic name of your organization and deployment as shown in the organization settings, which can contain spaces and capitalized characters.

The slugs displayed are the URL of your organization and deployment, with spaces replaced by a hyphen (-) and non-alphabetical characters (e.g., ()@#$%^, etc.) ignored.For example, if you're viewing a deployment called plugin picker (dev) and your organization is called Amazing Software, the URL will display as https://app.sleuth.io/amazing-software/deployments/plugin-picker-dev. Thus, the organization slug is amazing-software, the deployment slug is plugin-picker-dev.

Errors

  • Codes in the 2xx range indicate success

  • Codes in the 4xx range indicate incorrect or incomplete parameters

  • Codes in the 5xx range indicate an error with Sleuth servers

REST API Details

post
Deploy Registration

https://app.sleuth.io/api/1/<Organization Slug>/<Deployment Slug>/register_deploy
Register your deploys via the Sleuth API.
Request
Response
Request
Path Parameters
Organization Slug
required
string
Slug of the organization parent of the affected code deployment
Deployment Slug
required
string
Slug of the code deployment
Form Data Parameters
ignore_if_duplicate
optional
string
If the value is provided and set to "true" Sleuth won't return a 400 if we see a SHA that has already been registered
tags
optional
string
A comma-delimited list of tags. Defaults to tags calculated by matching paths defined in your .sleuth/TAGS file
environment
optional
string
String defining the environment to register the deploy against. If not provided Sleuth will use the default environment of the Project
email
optional
string
Email address of author
date
optional
string
ISO 8601 deployment date string
api_key
required
string
Located in the Organization Settings > Details > Api Key field
sha
required
string
The git SHA of the deployment, located in the deploy card of the deployment
Response
200: OK
Success
400: Bad Request
Input date problem, including if SHA doesn't exist or has already been reported.
String of message problem
401: Unauthorized
API key not valid or the deployment is not in the specific organization
String of message problem

post
Manual Change

https://app.sleuth.io/api/1/deployments/<Organization Slug>/<Project Slug>/register_manual_deploy
Manual changes are those not tracked by source code, feature flags, or any other type of change not supported by Sleuth. They are a free-form entry that includes a name and description. Although the description is optional, the form data in the manual change must contain a name as one of its parameters.
Request
Response
Request
Path Parameters
Organization Slug
required
string
Slug of the organization parent of the affected code deployment
Project Slug
required
string
Slug of the project that you're registering a deploy to
Form Data Parameters
tags
optional
string
A comma-delimited list of tag
api_key
required
string
Located in the Organization Settings > Details > Api Key field
email
optional
string
Email address of the user associated with the project receiving the manual change
name
required
string
Title for the manual change
description
optional
string
Description for the manual change
Response
200: OK
Success
400: Bad Request
Returned if the author or date are in the wrong format
Invalid date format. Must be in ISO 8601 format
401: Unauthorized
Returned if the API key provided doesn't allow access to the deployment
Unauthorized
404: Not Found
Returned if the project isn't found
Project not found
422: Unprocessable Entity
Name is required.

post
Custom Impact Registration

https://app.sleuth.io/api/1/impact/<Impact ID>/register_impact
You can submit custom impact values to Sleuth. Sleuth will perform its anomaly detection on these values and they will inform the health of your deploys. Values can represent any metric that matters to you and must be represented via a float.
Request
Response
Request
Path Parameters
Impact ID
optional
integer
Uniquely identifies the Impact Source to register a value against
Form Data Parameters
api_key
required
string
Located in the Organization Settings -> Details -> API Key field
date
optional
string
ISO 8601 date that indicates when the Impact value was collection. If not provided the date defaults to now
value
required
number
Float value that is the metric Sleuth will collect
Response
200: OK
Success
400: Bad Request
Returned if the value or date are malformed
Bad Request - impact value must be a number
401: Unauthorized
Returned if the API key provided doesn't allow you to access the Impact source
Unauthorized
404: Not Found
Returned if the Impact ID doesn't exist
MetricImpactSource <Impact ID> Not Found
429: Too Many Requests
Returned if your requests are more frequent than one every 120 seconds. A `Retry-After` header is provided with the number of seconds you should wait until you try again
You may only register a custom metric once every 120 seconds