Sleuth Manual Change API
Registers non-code, free-form manual changes (such as feature flag flips, infrastructure changes, or config updates) against a project so they appear on the Sleuth deploy timeline and factor into DORA metrics.
OpenAPI Specification
openapi: 3.0.1
info:
title: Sleuth Deployment & Impact Registration API
description: >-
The Sleuth registration API is a REST API used to push software delivery
events into Sleuth so it can compute DORA metrics (deploy frequency, lead
time, change failure rate, and time to restore). It covers code deploy
registration, free-form manual change registration, custom metric impact
values, and custom incident impact events. Sleuth's broader public API is a
GraphQL surface at https://app.sleuth.io/graphql. Requests authenticate with
an organization or scoped Access Token API key.
termsOfService: https://www.sleuth.io/terms
contact:
name: Sleuth Support
email: support@sleuth.io
version: '1'
servers:
- url: https://app.sleuth.io/api/1
description: Sleuth REST registration API
paths:
/deployments/{org_slug}/{deployment_slug}/register_deploy:
post:
operationId: registerDeploy
tags:
- Deployments
summary: Register a code deployment
description: >-
Registers a code deployment against a project's deployment and
environment by git SHA. If environment is omitted, the project's default
environment is used. The JSON schema is published at
https://app.sleuth.io/api/1/schema/register_deploy.
parameters:
- name: org_slug
in: path
required: true
description: URL-safe slug of your Sleuth organization.
schema:
type: string
- name: deployment_slug
in: path
required: true
description: URL-safe slug of the project deployment to register against.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterDeployRequest'
responses:
'200':
description: Deploy registered successfully.
content:
text/plain:
schema:
type: string
example: Success
'401':
description: Missing or invalid Access Token.
security:
- apiKeyAuth: []
/deployments/{org_slug}/{project_slug}/register_manual_deploy:
post:
operationId: registerManualChange
tags:
- Manual Changes
summary: Register a manual change
description: >-
Registers a non-code, free-form manual change (feature flag flip,
infrastructure change, config update, etc.) against a project so it
appears on the deploy timeline. The api_key may be supplied in the
Authorization header or in the request body, but not both.
parameters:
- name: org_slug
in: path
required: true
description: URL-safe slug of your Sleuth organization.
schema:
type: string
- name: project_slug
in: path
required: true
description: URL-safe slug of the project to register the change against.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterManualChangeRequest'
responses:
'200':
description: Manual change registered successfully.
content:
text/plain:
schema:
type: string
example: Success
'401':
description: Missing or invalid API key.
security:
- apiKeyAuth: []
/impact/{impact_id}/register_impact:
post:
operationId: registerMetricImpact
tags:
- Impact
summary: Register a custom metric impact value
description: >-
Registers a custom metric impact value against an impact source. Sleuth
runs anomaly detection on these values to grade deploy health. Limited
to one value every 120 seconds per impact source; dates may not predate
the impact source creation (no backfilling).
parameters:
- name: impact_id
in: path
required: true
description: Integer ID that uniquely identifies the Custom Metric Impact Source.
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterMetricImpactRequest'
responses:
'200':
description: Metric impact value registered successfully.
content:
text/plain:
schema:
type: string
example: Success
'401':
description: Missing or invalid API key.
'429':
description: Rate limited - at most one value every 120 seconds per source.
security:
- apiKeyAuth: []
/deployments/{org_slug}/{project_slug}/{environment_slug}/{impact_source_slug}/register_impact/{api_key}:
post:
operationId: registerIncidentImpact
tags:
- Impact
summary: Register a custom incident impact event
description: >-
Registers a custom incident impact event (triggered, resolved, or
reopened) against a custom incident impact source. The API key is
appended to the URL path.
parameters:
- name: org_slug
in: path
required: true
schema:
type: string
- name: project_slug
in: path
required: true
schema:
type: string
- name: environment_slug
in: path
required: true
schema:
type: string
- name: impact_source_slug
in: path
required: true
schema:
type: string
- name: api_key
in: path
required: true
description: Organization API key (Settings > Details > Api Key).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterIncidentImpactRequest'
responses:
'200':
description: Incident impact event registered successfully.
content:
text/plain:
schema:
type: string
example: Success
'401':
description: Missing or invalid API key.
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Sleuth Access Token / organization API key supplied as
"Authorization: apikey <APIKEY>". A Bearer token form
("Authorization: Bearer <ACCESS_TOKEN>") is also accepted for deploy
registration. Scoped Access Tokens are managed under Organization
Settings > Access Tokens.
schemas:
RegisterDeployRequest:
type: object
required:
- sha
properties:
sha:
type: string
description: Git SHA of the commit to register as a deploy.
environment:
type: string
description: Environment slug to register against; defaults to the project default.
date:
type: string
description: ISO-8601 timestamp of the deploy; defaults to the current time.
branch:
type: string
description: Git branch the deploy was made from.
tags:
type: string
description: Comma-separated tags to attach to the deploy.
ignore_if_duplicate:
type: string
description: When set, silently ignores a duplicate SHA instead of erroring.
email:
type: string
description: Email of the author associated with the deploy.
links:
type: string
description: Related links to attach to the deploy.
commits:
type: array
description: Commit objects included in the deploy.
items:
type: object
files:
type: array
description: Files changed in the deploy.
items:
type: string
pull_requests:
type: array
description: Pull requests included in the deploy.
items:
type: object
RegisterManualChangeRequest:
type: object
required:
- name
properties:
api_key:
type: string
description: API key, if not supplied via the Authorization header.
name:
type: string
description: Title for the manual change.
description:
type: string
description: Optional free-form description of the change.
environment:
type: string
description: Environment slug; defaults to the project default.
tags:
type: string
description: Comma-separated tags to attach to the change.
author:
type: string
description: Name of the author of the change.
email:
type: string
description: Email of the author of the change.
RegisterMetricImpactRequest:
type: object
required:
- value
properties:
value:
type: number
format: float
description: The metric value to register against the impact source.
api_key:
type: string
description: API key, if not supplied via the Authorization header.
date:
type: string
description: ISO-8601 timestamp; defaults to the current time. No backfilling.
RegisterIncidentImpactRequest:
type: object
required:
- type
properties:
type:
type: string
description: Incident event type.
enum:
- triggered
- resolved
- reopened
api_key:
type: string
description: API key (also appended to the URL path).
id:
type: string
description: Unique incident identifier from your system.
date:
type: string
description: ISO-8601 start timestamp; defaults to the current time.
ended_date:
type: string
description: ISO-8601 timestamp for when the incident ended.
title:
type: string
description: Human-readable incident name.
url:
type: string
description: Link to the incident in your external system.
security:
- apiKeyAuth: []