openapi: 3.0.1
info:
  title: Sleuth Deployment & Registration Deployments Impact 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: Impact
paths:
  /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:
  schemas:
    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.
  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.'