openapi: 3.0.1
info:
  title: Sleuth Deployment & Impact Registration Deployments 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
security:
- apiKeyAuth: []
tags:
- name: Deployments
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: []
components:
  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
  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.'