> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List findings

> List security findings (vulnerabilities, license violations, etc.) for the current organization, with optional filters.



## OpenAPI

````yaml https://api.app.chainloop.dev/openapi.yaml get /v1/findings
openapi: 3.0.1
info:
  contact:
    email: support@chainloop.dev
    name: Chainloop Support
    url: https://chainloop.dev
  termsOfService: https://chainloop.dev/terms
  title: Chainloop Platform API
  version: '1.0'
servers:
  - url: https://api.app.chainloop.dev/
security:
  - bearerToken: []
tags:
  - description: AI-powered agent operations
    name: AgentsService
  - name: ArtifactService
  - name: AssessmentService
  - description: Service for polling the status of asynchronous operations
    name: AsyncOperationsService
  - name: AttestationsService
  - name: PolicyService
  - name: ComplianceService
  - name: ComponentService
  - name: EnvironmentsService
  - name: EvidenceService
  - name: FindingService
  - name: LogicalEnvironmentsService
  - name: ProductsService
  - name: ProjectsService
  - name: UserService
externalDocs:
  description: Chainloop Official Documentation
  url: https://docs.chainloop.dev
paths:
  /v1/findings:
    get:
      tags:
        - FindingService
      summary: List findings
      description: >-
        List security findings (vulnerabilities, license violations, etc.) for
        the current organization, with optional filters.
      operationId: FindingService_List
      parameters:
        - description: |-
            Filter by project name

            Filter findings by project name
          in: query
          name: project_name
          schema:
            type: string
        - description: |-
            Filter by project version name

            Filter findings by project version name
          in: query
          name: project_version_name
          schema:
            type: string
        - description: |-
            Filter by severity levels

            Filter by one or more severity levels
          explode: true
          in: query
          name: severity
          schema:
            items:
              enum:
                - FINDING_SEVERITY_UNSPECIFIED
                - FINDING_SEVERITY_CRITICAL
                - FINDING_SEVERITY_HIGH
                - FINDING_SEVERITY_MEDIUM
                - FINDING_SEVERITY_LOW
                - FINDING_SEVERITY_INFO
                - FINDING_SEVERITY_UNKNOWN
              type: string
            type: array
          style: form
        - description: |-
            Filter by statuses

            Filter by one or more statuses

             - FINDING_STATUS_OPEN: OPEN: newly detected finding, not yet triaged or acted upon
             - FINDING_STATUS_IN_PROGRESS: IN_PROGRESS: finding is being investigated or actively remediated
             - FINDING_STATUS_RESOLVED: RESOLVED: finding has been fixed, mitigated, or otherwise closed (see resolution_reason for details)
             - FINDING_STATUS_REJECTED: REJECTED: finding has been dismissed by an operator (e.g. false positive, risk accepted, out of scope)
          explode: true
          in: query
          name: status
          schema:
            items:
              enum:
                - FINDING_STATUS_UNSPECIFIED
                - FINDING_STATUS_OPEN
                - FINDING_STATUS_IN_PROGRESS
                - FINDING_STATUS_RESOLVED
                - FINDING_STATUS_REJECTED
              type: string
            type: array
          style: form
        - description: |-
            Filter by finding types

            Filter by one or more finding types
          explode: true
          in: query
          name: finding_type
          schema:
            items:
              enum:
                - FINDING_TYPE_UNSPECIFIED
                - FINDING_TYPE_VULNERABILITY
              type: string
            type: array
          style: form
        - description: |-
            Filter by KEV membership

            Filter by whether the finding is in the CISA KEV catalog
          in: query
          name: is_in_kev
          schema:
            type: boolean
        - description: |-
            Search by external ID substring

            Search findings by external ID (e.g. CVE identifier)
          in: query
          name: search
          schema:
            type: string
        - description: >-
            The (zero-based) offset of the first item returned in the
            collection.
          in: query
          name: pagination.page
          schema:
            format: int32
            type: integer
        - description: >-
            The maximum number of entries to return. If the value exceeds the
            maximum, then the maximum value will be used.
          in: query
          name: pagination.page_size
          schema:
            format: int32
            type: integer
        - description: Sort field. Defaults to severity when not specified.
          in: query
          name: sort_by
          schema:
            default: FINDING_LIST_SORT_BY_UNSPECIFIED
            enum:
              - FINDING_LIST_SORT_BY_UNSPECIFIED
              - FINDING_LIST_SORT_BY_SEVERITY
              - FINDING_LIST_SORT_BY_LAST_SEEN_AT
              - FINDING_LIST_SORT_BY_FIRST_SEEN_AT
              - FINDING_LIST_SORT_BY_CREATED_AT
            type: string
        - description: Sort direction. Defaults to descending when not specified.
          in: query
          name: sort_direction
          schema:
            default: FINDING_LIST_SORT_DIRECTION_UNSPECIFIED
            enum:
              - FINDING_LIST_SORT_DIRECTION_UNSPECIFIED
              - FINDING_LIST_SORT_DIRECTION_ASC
              - FINDING_LIST_SORT_DIRECTION_DESC
            type: string
        - description: >-
            Filter by assessment status: true = only findings with at least one
            linked assessment, false = only unassessed findings


            Filter by whether the finding has been assessed
          in: query
          name: is_assessed
          schema:
            type: boolean
        - description: >-
            Filter by fixability: true = only findings with a fixed_version or
            recommendation, false = only without


            Filter by whether the finding has a fix available (fixed_version or
            recommendation)
          in: query
          name: is_fixable
          schema:
            type: boolean
        - description: >-
            Filter by artifact IDs (UUID); matches findings linked to any of the
            given artifacts
          explode: true
          in: query
          name: artifact_ids
          schema:
            items:
              type: string
            type: array
          style: form
        - description: Filter findings by associated software component ID (UUID)
          in: query
          name: component_id
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1FindingServiceListResponse'
          description: A successful response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1BadRequestResponse'
          description: Bad Request - The request was invalid or cannot be served.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UnauthorizedResponse'
          description: Unauthorized - Authentication is required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1PermissionDeniedResponse'
          description: Forbidden - You do not have permission to access this resource.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1InternalServerErrorResponse'
          description: Internal Server Error - An unexpected error occurred on the server.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
components:
  schemas:
    v1FindingServiceListResponse:
      description: Response for the List method
      example:
        pagination:
          total_count: 4
          page: 3
          total_pages: 7
          page_size: 2
        results:
          - severity: FINDING_SEVERITY_UNSPECIFIED
            package_purl: package_purl
            first_seen_at: '2000-01-23T04:56:07.000Z'
            recommendation: recommendation
            external_id: external_id
            source: source
            vulnerability:
              is_in_kev: true
              description: description
              cvss_vectors:
                - cvss_vectors
                - cvss_vectors
            finding_type: FINDING_TYPE_UNSPECIFIED
            project_name: project_name
            status_detail: FINDING_STATUS_DETAIL_UNSPECIFIED
            resolution_reason: FINDING_RESOLUTION_REASON_UNSPECIFIED
            project_version_name: project_version_name
            fixed_version: fixed_version
            artifact_ids:
              - artifact_ids
              - artifact_ids
            assessment_ids:
              - assessment_ids
              - assessment_ids
            id: id
            effective_assessment_status: ASSESSMENT_STATUS_UNSPECIFIED
            last_seen_at: '2000-01-23T04:56:07.000Z'
            status: FINDING_STATUS_UNSPECIFIED
          - severity: FINDING_SEVERITY_UNSPECIFIED
            package_purl: package_purl
            first_seen_at: '2000-01-23T04:56:07.000Z'
            recommendation: recommendation
            external_id: external_id
            source: source
            vulnerability:
              is_in_kev: true
              description: description
              cvss_vectors:
                - cvss_vectors
                - cvss_vectors
            finding_type: FINDING_TYPE_UNSPECIFIED
            project_name: project_name
            status_detail: FINDING_STATUS_DETAIL_UNSPECIFIED
            resolution_reason: FINDING_RESOLUTION_REASON_UNSPECIFIED
            project_version_name: project_version_name
            fixed_version: fixed_version
            artifact_ids:
              - artifact_ids
              - artifact_ids
            assessment_ids:
              - assessment_ids
              - assessment_ids
            id: id
            effective_assessment_status: ASSESSMENT_STATUS_UNSPECIFIED
            last_seen_at: '2000-01-23T04:56:07.000Z'
            status: FINDING_STATUS_UNSPECIFIED
      properties:
        results:
          items:
            $ref: '#/components/schemas/v1FindingListItem'
          title: The list of findings
          type: array
        pagination:
          $ref: '#/components/schemas/v1OffsetPaginationResponse'
      title: FindingServiceListResponse
      type: object
    v1BadRequestResponse:
      description: Response for bad request
      example:
        code: 0
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 3
          description: >-
            The error code indicating the type of error. It's fixed to 3, which
            is the code for INVALID_ARGUMENT.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: BadRequestResponse
      type: object
    v1UnauthorizedResponse:
      description: Response for unauthorized access
      example:
        code: 6
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 16
          description: >-
            The error code indicating the type of error. It's fixed to 16, which
            is the code for UNAUTHENTICATED.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: UnauthorizedResponse
      type: object
    v1PermissionDeniedResponse:
      description: Response for permission denied
      example:
        code: 1
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 7
          description: >-
            The error code indicating the type of error. It's fixed to 7, which
            is the code for PERMISSION_DENIED.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: PermissionDeniedResponse
      type: object
    v1InternalServerErrorResponse:
      description: Response for internal server error
      example:
        code: 5
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 13
          description: >-
            The error code indicating the type of error. It's fixed to 13, which
            is the code for INTERNAL_ERROR.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: InternalServerErrorResponse
      type: object
    rpcStatus:
      example:
        code: 5
        details:
          - '@type': '@type'
          - '@type': '@type'
        message: message
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
        details:
          items:
            $ref: '#/components/schemas/protobufAny'
          type: array
      type: object
    v1FindingListItem:
      description: Summary of a security finding
      example:
        severity: FINDING_SEVERITY_UNSPECIFIED
        package_purl: package_purl
        first_seen_at: '2000-01-23T04:56:07.000Z'
        recommendation: recommendation
        external_id: external_id
        source: source
        vulnerability:
          is_in_kev: true
          description: description
          cvss_vectors:
            - cvss_vectors
            - cvss_vectors
        finding_type: FINDING_TYPE_UNSPECIFIED
        project_name: project_name
        status_detail: FINDING_STATUS_DETAIL_UNSPECIFIED
        resolution_reason: FINDING_RESOLUTION_REASON_UNSPECIFIED
        project_version_name: project_version_name
        fixed_version: fixed_version
        artifact_ids:
          - artifact_ids
          - artifact_ids
        assessment_ids:
          - assessment_ids
          - assessment_ids
        id: id
        effective_assessment_status: ASSESSMENT_STATUS_UNSPECIFIED
        last_seen_at: '2000-01-23T04:56:07.000Z'
        status: FINDING_STATUS_UNSPECIFIED
      properties:
        id:
          description: Unique identifier of the finding
          title: Unique identifier of the finding
          type: string
        external_id:
          description: Vulnerability or finding identifier
          title: External identifier (e.g. CVE-2024-1234)
          type: string
        package_purl:
          description: Affected package in PURL format
          title: Affected package in PURL format
          type: string
        finding_type:
          $ref: '#/components/schemas/v1FindingType'
        severity:
          $ref: '#/components/schemas/v1FindingSeverity'
        status:
          $ref: '#/components/schemas/v1FindingStatus'
        source:
          description: Source tool or database
          title: Source tool or database that produced the finding
          type: string
        project_name:
          description: Name of the project
          title: Name of the project
          type: string
        project_version_name:
          description: Name of the project version
          title: Name of the project version
          type: string
        artifact_ids:
          description: IDs of artifacts affected by this finding
          items:
            type: string
          title: IDs of artifacts affected by this finding
          type: array
        first_seen_at:
          description: Timestamp when the finding was first detected
          format: date-time
          title: Timestamp when the finding was first detected
          type: string
        last_seen_at:
          description: Timestamp when the finding was last detected
          format: date-time
          title: Timestamp when the finding was last detected
          type: string
        status_detail:
          $ref: '#/components/schemas/v1FindingStatusDetail'
        resolution_reason:
          $ref: '#/components/schemas/v1FindingResolutionReason'
        assessment_ids:
          description: IDs of assessments linked to this finding
          items:
            type: string
          title: IDs of assessments linked to this finding
          type: array
        effective_assessment_status:
          $ref: '#/components/schemas/v1AssessmentStatus'
        vulnerability:
          $ref: '#/components/schemas/v1VulnerabilityListInfo'
        fixed_version:
          description: Version that fixes the vulnerability
          title: Version that fixes the vulnerability
          type: string
        recommendation:
          description: Remediation recommendation for the finding
          title: Remediation recommendation
          type: string
      title: FindingListItem
      type: object
    v1OffsetPaginationResponse:
      example:
        total_count: 4
        page: 3
        total_pages: 7
        page_size: 2
      properties:
        page:
          format: int32
          title: The current page number
          type: integer
        page_size:
          format: int32
          title: The number of results per page
          type: integer
        total_count:
          format: int32
          title: The total number of results
          type: integer
        total_pages:
          format: int32
          title: The total number of pages
          type: integer
      title: OffsetPaginationResponse is used to return the pagination information
      type: object
    protobufAny:
      additionalProperties:
        type: object
      example:
        '@type': '@type'
      properties:
        '@type':
          type: string
      type: object
    v1FindingType:
      default: FINDING_TYPE_UNSPECIFIED
      description: |-
        FindingType represents the type of security finding. Lives in
        shared_messages.proto for the same reason as FindingSeverity:
        assessment.proto needs it for the ListEffective query tuples without
        creating an import cycle with finding.proto.
      enum:
        - FINDING_TYPE_UNSPECIFIED
        - FINDING_TYPE_VULNERABILITY
      type: string
    v1FindingSeverity:
      default: FINDING_SEVERITY_UNSPECIFIED
      description: >-
        FindingSeverity represents the severity level of a finding. Lives in

        shared_messages.proto so both finding.proto and assessment.proto can use
        it

        without creating an import cycle (finding.proto imports assessment.proto
        for

        AssessmentStatus, and assessment.proto needs FindingSeverity for the

        severity field on AssessmentItem).
      enum:
        - FINDING_SEVERITY_UNSPECIFIED
        - FINDING_SEVERITY_CRITICAL
        - FINDING_SEVERITY_HIGH
        - FINDING_SEVERITY_MEDIUM
        - FINDING_SEVERITY_LOW
        - FINDING_SEVERITY_INFO
        - FINDING_SEVERITY_UNKNOWN
      type: string
    v1FindingStatus:
      default: FINDING_STATUS_UNSPECIFIED
      description: >-
        FindingStatus represents the lifecycle status of a finding.

        Transitions: OPEN → IN_PROGRESS → RESOLVED, or OPEN → REJECTED.

        A resolved finding can be reopened (back to OPEN) if it reappears in
        later evidence.

         - FINDING_STATUS_OPEN: OPEN: newly detected finding, not yet triaged or acted upon
         - FINDING_STATUS_IN_PROGRESS: IN_PROGRESS: finding is being investigated or actively remediated
         - FINDING_STATUS_RESOLVED: RESOLVED: finding has been fixed, mitigated, or otherwise closed (see resolution_reason for details)
         - FINDING_STATUS_REJECTED: REJECTED: finding has been dismissed by an operator (e.g. false positive, risk accepted, out of scope)
      enum:
        - FINDING_STATUS_UNSPECIFIED
        - FINDING_STATUS_OPEN
        - FINDING_STATUS_IN_PROGRESS
        - FINDING_STATUS_RESOLVED
        - FINDING_STATUS_REJECTED
      type: string
    v1FindingStatusDetail:
      default: FINDING_STATUS_DETAIL_UNSPECIFIED
      description: >-
        - FINDING_STATUS_DETAIL_MIXED_ASSESSMENTS: Active assessments at the
        same scope level disagree on status
      enum:
        - FINDING_STATUS_DETAIL_UNSPECIFIED
        - FINDING_STATUS_DETAIL_NEW
        - FINDING_STATUS_DETAIL_TRIAGED
        - FINDING_STATUS_DETAIL_REOPENED
        - FINDING_STATUS_DETAIL_INVESTIGATING
        - FINDING_STATUS_DETAIL_REMEDIATING
        - FINDING_STATUS_DETAIL_AWAITING_VERIFICATION
        - FINDING_STATUS_DETAIL_MIXED_ASSESSMENTS
      title: FindingStatusDetail provides additional context about the finding status
      type: string
    v1FindingResolutionReason:
      default: FINDING_RESOLUTION_REASON_UNSPECIFIED
      enum:
        - FINDING_RESOLUTION_REASON_UNSPECIFIED
        - FINDING_RESOLUTION_REASON_FIXED
        - FINDING_RESOLUTION_REASON_OBJECT_DELETED
        - FINDING_RESOLUTION_REASON_MITIGATED
        - FINDING_RESOLUTION_REASON_FALSE_POSITIVE
        - FINDING_RESOLUTION_REASON_NOT_AFFECTED
        - FINDING_RESOLUTION_REASON_RISK_ACCEPTED
        - FINDING_RESOLUTION_REASON_WONT_FIX
        - FINDING_RESOLUTION_REASON_DUPLICATE
        - FINDING_RESOLUTION_REASON_OUT_OF_SCOPE
      title: >-
        FindingResolutionReason represents the reason a finding was resolved or
        rejected
      type: string
    v1AssessmentStatus:
      default: ASSESSMENT_STATUS_UNSPECIFIED
      enum:
        - ASSESSMENT_STATUS_UNSPECIFIED
        - ASSESSMENT_STATUS_NOT_AFFECTED
        - ASSESSMENT_STATUS_AFFECTED
        - ASSESSMENT_STATUS_UNDER_INVESTIGATION
        - ASSESSMENT_STATUS_FIXED
      title: AssessmentStatus represents the OpenVEX-aligned status
      type: string
    v1VulnerabilityListInfo:
      description: Subset of vulnerability metadata for list responses
      example:
        is_in_kev: true
        description: description
        cvss_vectors:
          - cvss_vectors
          - cvss_vectors
      properties:
        description:
          description: Human-readable description of the vulnerability
          title: Human-readable description
          type: string
        cvss_vectors:
          description: CVSS vector strings
          items:
            type: string
          title: CVSS vector strings
          type: array
        is_in_kev:
          description: >-
            Whether this CVE is in the CISA Known Exploited Vulnerabilities
            catalog
          title: Whether this CVE is in the CISA KEV catalog
          type: boolean
      title: VulnerabilityListInfo
      type: object
  securitySchemes:
    bearerToken:
      description: Bearer token for authentication
      type: http
      scheme: bearer
      bearerFormat: JWT

````