openapi: 3.0.3
info:
  title: GitKraken Public API
  description: |
    The public REST API for GitKraken.

    This reference documents the subset of the GitKraken API exposed on the
    public developer portal. See the guides for authentication, rate limiting,
    and end-to-end workflows.
  termsOfService: https://www.gitkraken.com/api-terms-of-use
  contact:
    email: api@gitkraken.com
  version: 1.0.0
servers:
  - url: https://staging-api.gitkraken.dev
tags:
  - name: Insights
    description: API endpoints for accessing insights and analytics data including DORA metrics, pull request analytics, and repository information.
paths:
  /v1/insights/dora/{metric}:
    get:
      tags:
        - Insights
      summary: Get DORA Metric Report
      description: Retrieves a DORA metric report for the specified repositories and timeframe
      operationId: getDoraMetric
      parameters:
        - name: metric
          in: path
          required: true
          schema:
            type: string
            enum:
              - deploy_frequency
              - change_lead_time
              - mean_time_to_recover
              - defect_rate
              - change_failure_rate
              - bug_escape_rate
          description: The DORA metric to retrieve
        - name: repo
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Repository identifiers to include in the report
        - name: team
          in: query
          schema:
            type: string
          description: Team identifier to filter by
        - name: startDate
          in: query
          schema:
            type: string
            format: date
          description: Start date for the report (YYYY-MM-DD)
        - name: endDate
          in: query
          schema:
            type: string
            format: date
          description: End date for the report (YYYY-MM-DD)
        - name: groupBy
          in: query
          schema:
            type: string
            enum:
              - repo
              - team
            default: repo
          description: Group results by repository or team. Default is 'repo'. Response format changes based on this parameter.
        - name: trendlineType
          in: query
          schema:
            type: string
            enum:
              - linear
              - polynomial
              - moving_average
          description: Type of trendline to apply to the time series data. When specified, the response values will be transformed to show the trendline instead of raw values.
        - name: windowSize
          in: query
          schema:
            type: integer
            minimum: 1
            default: 3
          description: Window size for moving average trendline calculation. Only applicable when trendlineType is 'moving_average'.
        - name: aggregateOnly
          in: query
          schema:
            type: boolean
            default: false
          description: When true, returns only the aggregated data (all-repos or all-teams) without the per-repository or per-team breakdown.
      responses:
        '200':
          $ref: '#/components/responses/DoraReportResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/insights/dora/{metric}/summary:
    get:
      tags:
        - Insights
      summary: Get DORA Metric Summary
      description: Retrieves a DORA metric summary for the specified repositories
      operationId: getDoraMetricSummary
      parameters:
        - name: metric
          in: path
          required: true
          schema:
            type: string
            enum:
              - deploy_frequency
              - change_lead_time
              - mean_time_to_recover
              - defect_rate
              - change_failure_rate
          description: The DORA metric to retrieve. Note `bug_escape_rate` is not supported on this endpoint — its GitClear summary stats are generic activity counters, not a rate, so the summary handler returns 400 for that metric.
        - name: repo
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Repository identifiers to include in the summary
        - name: team
          in: query
          schema:
            type: string
          description: Team identifier to filter by
        - name: startDate
          in: query
          schema:
            type: string
            format: date
          description: Start date for the report (YYYY-MM-DD)
        - name: endDate
          in: query
          schema:
            type: string
            format: date
          description: End date for the report (YYYY-MM-DD)
      responses:
        '200':
          $ref: '#/components/responses/DoraMetricSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/insights/repositories:
    get:
      tags:
        - Insights
      summary: Search Repositories
      description: Search for repositories available to the user
      operationId: searchRepositories
      parameters:
        - name: repo
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Repository identifiers to filter by
      responses:
        '200':
          $ref: '#/components/responses/RepositoryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/insights/teams:
    get:
      tags:
        - Insights
      summary: Search Teams
      description: Search for teams within the organization
      operationId: searchTeams
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: team
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Team identifiers to filter by
        - name: username
          in: query
          schema:
            type: string
          description: Provider username to filter teams by
      responses:
        '200':
          $ref: '#/components/responses/TeamsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/insights/releases:
    get:
      tags:
        - Insights
      summary: Search Repository Releases
      description: Retrieves release data and metrics for a specified repository, including commit counts, defect counts, and deployment information
      operationId: searchReleases
      parameters:
        - name: repo
          in: query
          required: true
          schema:
            type: string
          description: Repository identifier to retrieve releases for
        - name: team
          in: query
          schema:
            type: string
          description: Team identifier to filter releases by
        - name: startDate
          in: query
          schema:
            type: string
            format: date
          description: Start date for filtering releases (YYYY-MM-DD)
        - name: endDate
          in: query
          schema:
            type: string
            format: date
          description: End date for filtering releases (YYYY-MM-DD)
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Number of results per page
      responses:
        '200':
          $ref: '#/components/responses/ReleasesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Insights
      summary: Create Release
      description: |
        Creates a release for a specified repository.

        At least one of `releasedAt`, `releaseSha`, or `releaseNow` must be provided to determine the release timing.
      operationId: createRelease
      requestBody:
        $ref: '#/components/requestBodies/CreateReleaseRequest'
      responses:
        '201':
          description: Release created successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/insights/critical-defects:
    post:
      tags:
        - Insights
      summary: Create Critical Defect
      description: |
        Record a critical defect for a repository. This creates a defect record that can be used
        to track known issues and their resolution status.

        Either `detectedAt` or `detectedNow` must be provided to indicate when the defect was detected.
      operationId: createCriticalDefect
      requestBody:
        $ref: '#/components/requestBodies/CreateCriticalDefectRequest'
      responses:
        '201':
          description: Critical defect created successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Point:
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: Start date of the interval
          example: '2024-01-15'
        endDate:
          type: string
          format: date
          description: End date of the interval (for weekly intervals, 6 days after start; for monthly, last day of month; for daily, same as start)
          example: '2024-01-21'
        value:
          type: number
          format: double
          description: Metric value for this data point
          example: 3.5
      required:
        - startDate
        - endDate
        - value
    BaseMetricResponse:
      type: object
      properties:
        providerOrgId:
          type: string
          description: Provider organization identifier
          example: gitkraken
        interval:
          type: string
          description: Time interval for the metric
          example: daily
        metric:
          type: string
          description: Metric name
          example: deploy_frequency
        unit:
          type: string
          description: Canonical unit of measurement for the metric values
          example: commit
        trendlineType:
          type: string
          description: Type of trendline applied to the data (if any)
          enum:
            - linear
            - polynomial
            - moving_average
          example: linear
        timeSeries:
          type: array
          items:
            $ref: '#/components/schemas/Point'
          description: Time series data points
      required:
        - providerOrgId
        - interval
        - metric
        - timeSeries
    DoraMetricResponse:
      allOf:
        - $ref: '#/components/schemas/BaseMetricResponse'
        - description: DORA metric response (no contributors field)
    BaseMetricResponseTeamGrouped:
      type: object
      properties:
        providerOrgId:
          type: string
          description: Provider organization identifier
          example: gitkraken
        interval:
          type: string
          description: Time interval for the metric
          example: daily
        metric:
          type: string
          description: Metric name
          example: deploy_frequency
        unit:
          type: string
          description: Canonical unit of measurement for the metric values
          example: commit
        trendlineType:
          type: string
          description: Type of trendline applied to the data (if any)
          enum:
            - linear
            - polynomial
            - moving_average
          example: linear
        timeSeries:
          type: array
          items:
            $ref: '#/components/schemas/Point'
          description: Time series data points
      required:
        - providerOrgId
        - interval
        - metric
        - timeSeries
    DoraMetricResponseTeamGrouped:
      allOf:
        - $ref: '#/components/schemas/BaseMetricResponseTeamGrouped'
        - description: DORA metric response for team-grouped data
    APIError:
      title: APIError
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: The error message
    DoraDeploymentFrequency:
      type: object
      properties:
        perWeek:
          type: number
          format: double
          description: Deployments per week
          example: 5.2
        perWeekday:
          type: number
          format: double
          description: Deployments per weekday
          example: 1.04
        previousPerWeekday:
          type: number
          format: double
          description: Previous period deployments per weekday
          example: 0.8
        percentChange:
          type: integer
          format: int64
          description: Percent change from previous period
          example: 30
        previousPeriodSum:
          type: integer
          format: int64
          description: Total deployments in previous period
          example: 20
        total:
          type: integer
          format: int64
          description: Total deployments in current period
          example: 26
        units:
          type: string
          description: Canonical unit of measurement
          example: release
        tooltipText:
          type: string
          description: Tooltip text with additional context
          example: Deployment frequency increased by 30% compared to previous period
      required:
        - perWeek
        - perWeekday
        - previousPerWeekday
        - percentChange
        - previousPeriodSum
        - total
        - tooltipText
    DoraSummaryMetric:
      type: object
      description: Summary statistics for change_lead_time, mean_time_to_recover, defect_rate, and change_failure_rate metrics.
      properties:
        percentChange:
          type: number
          format: double
          description: Percent change from previous period
          example: -15.5
        previousPeriodSum:
          type: number
          format: double
          description: Sum for previous period
          example: 4.2
        total:
          type: number
          format: double
          description: Total for current period
          example: 3.6
        units:
          type: string
          description: Units of measurement (e.g. "day", "hour", or "%" for rate metrics)
          example: hours
        tooltipText:
          type: string
          description: Tooltip text with additional context
          example: Mean time to recover decreased by 15.5% compared to previous period
      required:
        - percentChange
        - previousPeriodSum
        - total
        - units
        - tooltipText
    DoraMetricSummary:
      type: object
      properties:
        providerOrgId:
          type: string
          description: Provider organization identifier
          example: gitkraken
        metric:
          type: string
          description: Metric name
          example: deploy_frequency
        interval:
          type: string
          description: Time interval
          example: week
        summaryStats:
          oneOf:
            - $ref: '#/components/schemas/DoraDeploymentFrequency'
            - $ref: '#/components/schemas/DoraSummaryMetric'
          description: Summary statistics for the requested metric. Returns DoraDeploymentFrequency for deploy_frequency, or DoraSummaryMetric for change_lead_time, mean_time_to_recover, defect_rate, and change_failure_rate.
      required:
        - metric
        - interval
        - summaryStats
    Repository:
      type: object
      properties:
        providerId:
          type: string
          description: Provider identifier (e.g., github, gitlab)
          example: github
        providerOrgId:
          type: string
          description: Organization identifier within the provider
          example: gitkraken
        name:
          type: string
          description: Repository name
          example: gitlens
      required:
        - providerId
        - providerOrgId
        - name
    RepositoryStatus:
      allOf:
        - $ref: '#/components/schemas/Repository'
        - type: object
          properties:
            status:
              type: string
              description: Processing status of the repository
              example: success
            createdAt:
              type: string
              format: date-time
              description: Creation timestamp
              example: '2024-01-15T09:00:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp
              example: '2024-01-15T10:30:00Z'
            lastDeployedAt:
              type: string
              format: date-time
              description: Last deployment timestamp
              example: '2024-01-15T09:45:00Z'
            lastProcessedAt:
              type: string
              format: date-time
              description: Last processing timestamp
              example: '2024-01-15T10:15:00Z'
            processingPercentComplete:
              type: number
              format: double
              description: Processing completion percentage
              minimum: 0
              maximum: 100
              example: 95.5
            commitsProcessed:
              type: integer
              format: int64
              description: Number of commits processed
              example: 1250
    BaseContributor:
      type: object
      properties:
        providerId:
          type: string
          description: Provider identifier
          example: github
        providerUsername:
          type: string
          description: Provider username
          example: eamodio
        providerUserId:
          type: string
          description: Provider user identifier (only supplied when data is present)
          example: '123456'
      required:
        - providerId
        - providerUsername
    Team:
      type: object
      properties:
        id:
          type: string
          description: Team identifier
          example: frontend-team
        name:
          type: string
          description: Team name
          example: Frontend Development Team
        contributors:
          type: array
          items:
            $ref: '#/components/schemas/BaseContributor'
          description: List of team contributors (base information only)
        repos:
          type: array
          items:
            $ref: '#/components/schemas/Repository'
          description: List of repositories associated with the team
      required:
        - id
        - name
        - contributors
        - repos
    ContributorTeam:
      type: object
      properties:
        id:
          type: string
          description: Team identifier
          example: team-123
        name:
          type: string
          description: Team name
          example: Frontend Team
      required:
        - id
        - name
    Contributor:
      allOf:
        - $ref: '#/components/schemas/BaseContributor'
        - type: object
          properties:
            name:
              type: string
              description: Contributor name (only supplied when data is present)
              example: Eric Amodio
            email:
              type: string
              description: Contributor email (only supplied when data is present)
              example: eric@gitkraken.com
            processingStatus:
              type: string
              description: Processing status of the contributor
              example: enabled
            isTracked:
              type: boolean
              description: Whether the contributor is tracked and consumes a license
              example: true
            lastCommittedAt:
              type: string
              description: The last time the contributor commited code
              example: '2021-12-17T07:42:08.000Z'
            teams:
              type: array
              items:
                $ref: '#/components/schemas/ContributorTeam'
              description: Teams associated with the contributor
          required:
            - processingStatus
            - isTracked
            - teams
    Release:
      type: object
      properties:
        id:
          type: integer
          description: Unique release identifier
          example: 12345
        name:
          type: string
          description: Release name/tag
          example: v2.1.0
        repo:
          type: string
          description: Repository path
          example: gitkraken/gitlens
        releasedAt:
          type: string
          format: date-time
          description: When the release was deployed
          example: '2024-01-15T09:45:00Z'
        commitCount:
          type: integer
          description: Number of commits in this release
          example: 45
        defectCount:
          type: integer
          description: Number of defects found in this release
          example: 2
        issueCount:
          type: integer
          description: Number of issues addressed in this release
          example: 8
        triggeredBy:
          type: string
          description: What triggered this release
          example: manual
        deployedBy:
          $ref: '#/components/schemas/Contributor'
      required:
        - id
        - name
        - repo
        - releasedAt
        - commitCount
        - defectCount
        - issueCount
        - deployedBy
  responses:
    DoraReportResponse:
      description: |
        Successful DORA metric report response.
        Response structure changes based on the groupBy query parameter:
        - When groupBy=repo (default): Returns 'all-repos' and 'repos' fields
        - When groupBy=team: Returns 'all-teams' and 'teams' fields
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                oneOf:
                  - type: object
                    description: Response when groupBy=repo (default)
                    properties:
                      all-repos:
                        allOf:
                          - $ref: '#/components/schemas/DoraMetricResponse'
                          - description: Aggregated DORA metric data across all repositories
                      repos:
                        type: object
                        additionalProperties:
                          $ref: '#/components/schemas/DoraMetricResponse'
                        description: Per-repository DORA metric data, where keys are repository names
                        example:
                          gitlens:
                            providerOrgId: gitkraken
                            interval: daily
                            metric: deploy_frequency
                            timeSeries: []
                          gitkraken-cli:
                            providerOrgId: gitkraken
                            interval: daily
                            metric: deploy_frequency
                            timeSeries: []
                    required:
                      - all-repos
                      - repos
                  - type: object
                    description: Response when groupBy=team
                    properties:
                      all-teams:
                        allOf:
                          - $ref: '#/components/schemas/DoraMetricResponseTeamGrouped'
                          - description: Aggregated DORA metric data across all teams
                      teams:
                        type: object
                        additionalProperties:
                          $ref: '#/components/schemas/DoraMetricResponseTeamGrouped'
                        description: Per-team DORA metric data, where keys are team names
                    required:
                      - all-teams
                      - teams
            required:
              - data
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    UnauthenticatedError:
      description: Unauthenticated Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    UnauthorizedError:
      description: Unauthorized Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    DoraMetricSummaryResponse:
      description: Successful DORA metric summary response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  all-repos:
                    allOf:
                      - $ref: '#/components/schemas/DoraMetricSummary'
                      - description: Aggregated DORA metric summary across all repositories
                required:
                  - all-repos
            required:
              - data
    RepositoryResponse:
      description: Successful repository search response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  repos:
                    type: array
                    items:
                      $ref: '#/components/schemas/RepositoryStatus'
                  totalCount:
                    type: integer
                    description: Total number of repositories
                  totalPages:
                    type: integer
                    description: Total number of pages
                  pageSize:
                    type: integer
                    description: Number of items per page
                  sortBy:
                    type: string
                    description: Sort by field
                  sortDir:
                    type: string
                    description: Sort direction
                  page:
                    type: integer
                    description: Current page number
                required:
                  - repos
            required:
              - data
    TeamsResponse:
      description: Successful teams search response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
                  totalCount:
                    type: integer
                    description: Total number of repositories
                  totalPages:
                    type: integer
                    description: Total number of pages
                  pageSize:
                    type: integer
                    description: Number of items per page
                  sortBy:
                    type: string
                    description: Sort by field
                  sortDir:
                    type: string
                    description: Sort direction
                  page:
                    type: integer
                    description: Current page number
                required:
                  - results
            required:
              - data
    ReleasesResponse:
      description: Successful releases search response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Release'
                    description: List of releases for the specified repository
                  totalCount:
                    type: integer
                    description: Total number of releases
                    example: 125
                  totalPages:
                    type: integer
                    description: Total number of pages
                    example: 5
                  pageSize:
                    type: integer
                    description: Number of items per page
                    example: 25
                  page:
                    type: integer
                    description: Current page number
                    example: 1
                required:
                  - results
                  - totalCount
                  - totalPages
                  - pageSize
                  - page
            required:
              - data
  requestBodies:
    CreateReleaseRequest:
      description: Request body for creating a release
      content:
        application/json:
          schema:
            type: object
            required:
              - repo
            properties:
              repo:
                type: string
                description: Repository path in owner/repo format
                example: gitkraken/gitlens
              name:
                type: string
                description: Release identifier (e.g. version tag)
                example: v1.2.3
              releasedAt:
                type: string
                description: |
                  Time the release occurred. Accepts datetime strings (ISO 8601, e.g. "2025-03-21T22:50:03Z") or epoch seconds as a string (e.g. "1711061403"). Required unless releaseSha or releaseNow is provided.
                example: '2025-03-21T22:50:03Z'
              releaseNow:
                type: boolean
                description: Mark the release as occurring at the time of the API call
                example: true
              releaseSha:
                type: string
                description: Commit SHA of the release. If releasedAt is not provided, the commit's authorship timestamp is used.
                example: a1b2c3d4e5f6
              issueKeysResolved:
                type: array
                items:
                  type: string
                description: Issue keys deployed in this release (used for DORA Lead Time calculation)
                example:
                  - PROJ-123
                  - PROJ-456
              defectKeysResolved:
                type: array
                items:
                  type: string
                description: Critical defect keys resolved in this release
                example:
                  - BUG-789
              deployCommitterUserName:
                type: string
                description: Git provider username of the person who deployed the release
                example: octocat
    CreateCriticalDefectRequest:
      description: Request body for creating a critical defect
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              repo:
                type: string
                description: Repository identifier in owner/repo format
                pattern: ^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$
                example: acme-corp/api-service
              defectKey:
                type: string
                description: Unique identifier for the defect (e.g., issue tracker key)
                example: JIRA-1234
              detectedAt:
                type: string
                description: When the defect was detected, as an ISO 8601 datetime string or Unix epoch seconds. Either this or `detectedNow` must be provided.
                example: '2026-03-15T14:30:00Z'
              detectedNow:
                type: boolean
                description: Set to true to record the defect as detected at the current time. Either this or `detectedAt` must be provided.
                example: true
              description:
                type: string
                description: Description of the defect
                example: SQL injection vulnerability in user search endpoint
              category:
                type: string
                description: Category of the defect (e.g., security, performance, reliability)
                example: security
              severity:
                type: integer
                description: Severity level of the defect
                example: 3
              fixAppliedAt:
                type: string
                description: When the fix was applied, as an ISO 8601 datetime string or Unix epoch seconds
                example: '2026-03-16T10:00:00Z'
              fixReleasedAt:
                type: string
                description: When the fix was released, as an ISO 8601 datetime string or Unix epoch seconds
                example: '2026-03-17T12:00:00Z'
              fixReleasedNow:
                type: boolean
                description: Set to true to record the fix as released at the current time
                example: true
              fixReleasedSha:
                type: string
                description: Git commit SHA of the fix release (short or full hex SHA, 4–40 characters)
                pattern: ^[0-9a-fA-F]{4,40}$
                minLength: 4
                maxLength: 40
                example: a1b2c3d4e5f6
              fixReleasedRepoPath:
                type: string
                description: Repository path where the fix was released, in owner/repo format
                pattern: ^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$
                example: acme-corp/api-service
            required:
              - repo
              - defectKey