openapi: 3.0.1
info:
  title: Trunk Flaky Tests API
  description: HTTP REST API for the Trunk platform. Covers the Flaky Tests API (query test-case state, list quarantined / unhealthy / failing tests, link external tickets) and the Merge Queue API (control the flake-aware parallel merge queue and read its metrics). All requests are authenticated with an organization API token passed in the x-api-token header and return JSON.
  termsOfService: https://trunk.io/legal/terms
  contact:
    name: Trunk Support
    url: https://docs.trunk.io
  version: '1.0'
servers:
- url: https://api.trunk.io/v1
  description: Trunk REST API
security:
- ApiKeyAuth: []
tags:
- name: Flaky Tests
  description: Query Flaky Tests state and link tickets.
paths:
  /flaky-tests/get-test-details:
    post:
      operationId: getTestDetails
      tags:
      - Flaky Tests
      summary: Get the details of a test case
      description: Fetch detailed metadata for a single test case, including its current status, recent failure rates, most common failures, codeowners, and quarantine state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repo
              - org_url_slug
              - test_id
              properties:
                repo:
                  $ref: '#/components/schemas/Repo'
                org_url_slug:
                  type: string
                  description: Organization slug from Trunk settings.
                  example: my-trunk-org-slug
                test_id:
                  type: string
                  format: uuid
                  description: Stable unique test-case identifier.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  test:
                    $ref: '#/components/schemas/TestDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /flaky-tests/list-quarantined-tests:
    post:
      operationId: listQuarantinedTests
      tags:
      - Flaky Tests
      summary: Get a list of quarantined tests
      description: List tests currently quarantined in a repository, with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repo
              - org_url_slug
              - page_query
              properties:
                repo:
                  $ref: '#/components/schemas/Repo'
                org_url_slug:
                  type: string
                page_query:
                  $ref: '#/components/schemas/PageQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  quarantined_tests:
                    type: array
                    items:
                      $ref: '#/components/schemas/TestDetail'
                  page:
                    $ref: '#/components/schemas/Page'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /flaky-tests/list-unhealthy-tests:
    post:
      operationId: listUnhealthyTests
      tags:
      - Flaky Tests
      summary: Get a list of unhealthy tests
      description: List unhealthy tests in a repository, filtered by status (FLAKY or BROKEN), with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repo
              - org_url_slug
              - page_query
              - status
              properties:
                repo:
                  $ref: '#/components/schemas/Repo'
                org_url_slug:
                  type: string
                page_query:
                  $ref: '#/components/schemas/PageQuery'
                status:
                  type: string
                  enum:
                  - FLAKY
                  - BROKEN
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  tests:
                    type: array
                    items:
                      $ref: '#/components/schemas/TestDetail'
                  page:
                    $ref: '#/components/schemas/Page'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /flaky-tests/list-failing-tests:
    post:
      operationId: listFailingTests
      tags:
      - Flaky Tests
      summary: Get a list of distinct tests that failed in the given time range
      description: List distinct tests that failed within an inclusive start / exclusive end time range, with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repo
              - org_url_slug
              - start_time
              - end_time
              - page_query
              properties:
                repo:
                  $ref: '#/components/schemas/Repo'
                org_url_slug:
                  type: string
                start_time:
                  type: string
                  format: date-time
                  description: Inclusive start of the time range.
                end_time:
                  type: string
                  format: date-time
                  description: Exclusive end of the time range.
                page_query:
                  $ref: '#/components/schemas/PageQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  tests:
                    type: array
                    items:
                      $ref: '#/components/schemas/TestDetail'
                  page:
                    $ref: '#/components/schemas/Page'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /flaky-tests/link-ticket-to-test-case:
    post:
      operationId: linkTicketToTestCase
      tags:
      - Flaky Tests
      summary: Link a ticket to a test case
      description: Associate an external ticket (e.g. Jira "KAN-123" or Linear "TRUNK-1234") with a Trunk test case.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repo
              - test_case_id
              - external_ticket_id
              properties:
                repo:
                  $ref: '#/components/schemas/Repo'
                test_case_id:
                  type: string
                  format: uuid
                external_ticket_id:
                  type: string
                  example: KAN-123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Repo:
      type: object
      required:
      - host
      - owner
      - name
      properties:
        host:
          type: string
          description: Repository host, e.g. github.com or gitlab.com.
          example: github.com
        owner:
          type: string
          example: my-org
        name:
          type: string
          example: my-repo
    Status:
      type: object
      properties:
        value:
          type: string
          enum:
          - HEALTHY
          - FLAKY
          - BROKEN
        reason:
          type: string
        timestamp:
          type: string
          format: date-time
    Page:
      type: object
      properties:
        total_rows:
          type: integer
        total_pages:
          type: integer
        page_index:
          type: integer
        next_page_token:
          type: string
        prev_page_token:
          type: string
        last_page_token:
          type: string
    TestDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        variant:
          type: string
        classname:
          type: string
        file_path:
          type: string
        status:
          $ref: '#/components/schemas/Status'
        failure_rate_last_7d:
          type: number
        failure_rate_last_24h:
          type: number
        most_common_failures:
          type: array
          items:
            type: object
            properties:
              summary:
                type: string
              count:
                type: integer
        quarantined:
          type: boolean
        codeowners:
          type: array
          items:
            type: string
        pull_requests_impacted_last_7d:
          type: integer
        html_url:
          type: string
        ticket:
          type: object
          properties:
            html_url:
              type: string
    PageQuery:
      type: object
      required:
      - page_size
      properties:
        page_size:
          type: integer
          minimum: 1
          maximum: 100
        page_token:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-token
      description: Organization API token from Settings > Organization > General > API.