Snyk Findings API

openapi: 3.0.3
info:
  title: Snyk AccessRequests Findings API
  version: REST
servers:
- description: Snyk REST API
  url: https://api.snyk.io/rest
security:
- APIToken: []
- BearerAuth: []
tags:
- name: Findings
paths:
  /orgs/{org_id}/tests/{test_id}/findings:
    get:
      description: 'List findings for a test.


        Test Findings are scanner-agnostic representations of

        vulnerabilities and organization-level policy breaches.

        When Snyk runs a Test, the results of that Test are

        formatted into Findings.


        This endpoint returns pages of Findings associated with

        a given Test ID. Findings are returned in sorted order by

        ID, with page size equal to the provided Limit query parameter.

        Page size is 10 Findings by default if no parameter is provided.


        Note that the Findings returned from this endpoint are only the

        Findings that are _not_ suppressed by policy and are _not_

        in violation of a set Test threshold (like Severity or Risk Score).


        To retrieve the next (or previous) page of Findings, utilize the

        Next and Prev links returned in the response.


        #### Required permissions


        - `View Organization (org.read)`'
      operationId: listFindings
      parameters:
      - $ref: '#/components/parameters/io.snyk.api.request.SnykApiRequest.request_id'
      - $ref: '#/components/parameters/io.snyk.api.request.SnykApiRequest.interaction_id'
      - $ref: '#/components/parameters/io.snyk.api.request.SnykApiRequest.version'
      - $ref: '#/components/parameters/io.snyk.api.request.PaginatedRequest.starting_after'
      - $ref: '#/components/parameters/io.snyk.api.request.PaginatedRequest.ending_before'
      - $ref: '#/components/parameters/io.snyk.api.request.PaginatedRequest.limit'
      - description: 'Snyk Org ID under which to run or query information

          about a Job or Test.'
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/TestIdParam'
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/FindingData'
                    type: array
                  jsonapi:
                    $ref: '#/components/schemas/io.snyk.api.common.JsonApi'
                  links:
                    $ref: '#/components/schemas/io.snyk.api.common.PaginatedLinks'
                  meta:
                    $ref: '#/components/schemas/io.snyk.api.common.Meta'
                required:
                - data
                - jsonapi
                - links
                type: object
          description: Successful API response for a paginated collection.
          headers:
            deprecation:
              schema:
                type: string
            snyk-request-id:
              schema:
                type: string
            snyk-version-lifecycle-stage:
              schema:
                type: string
            snyk-version-requested:
              schema:
                type: string
            snyk-version-served:
              schema:
                type: string
            sunset:
              description: 'A header containing the date of when the underlying endpoint will be removed. This header is only present if the endpoint has been deprecated. For information purposes only. Returned as a date in the format: YYYY-MM-DD'
              example: '2021-08-02'
              schema:
                format: date
                type: string
        '400':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/io.snyk.api.common.ErrorDocument'
          description: Invalid input
          headers:
            deprecation:
              schema:
                type: string
            snyk-request-id:
              schema:
                type: string
            snyk-version-lifecycle-stage:
              schema:
                type: string
            snyk-version-requested:
              schema:
                type: string
            snyk-version-served:
              schema:
                type: string
            sunset:
              description: 'A header containing the date of when the underlying endpoint will be removed. This header is only present if the endpoint has been deprecated. For information purposes only. Returned as a date in the format: YYYY-MM-DD'
              example: '2021-08-02'
              schema:
                format: date
                type: string
      summary: List findings for a test. (Early Access)
      tags:
      - Findings
      x-snyk-api-lifecycle: released
      x-snyk-api-releases:
      - 2024-10-15~beta
      x-snyk-api-resource: tests
      x-snyk-api-stability: beta
      x-snyk-api-version: 2024-10-15~beta
      x-stability-level: beta
components:
  parameters:
    io.snyk.api.request.PaginatedRequest.starting_after:
      description: Opaque pagination cursor for forward traversal.
      explode: false
      in: query
      name: starting_after
      schema:
        type: string
    io.snyk.api.request.PaginatedRequest.limit:
      description: The number of items to return.
      explode: false
      in: query
      name: limit
      schema:
        default: 10
        format: int8
        maximum: 100
        minimum: 1
        type: integer
    io.snyk.api.request.PaginatedRequest.ending_before:
      description: Opaque pagination cursor for reverse traversal.
      explode: false
      in: query
      name: ending_before
      schema:
        type: string
    io.snyk.api.request.SnykApiRequest.interaction_id:
      description: 'Identifies the Snyk client interaction in which this API request occurs.


        The identifier is an opaque string. though at the time of writing it may either be a

        uuid or a urn containing a uuid and some metadata.'
      in: header
      name: snyk-interaction-id
      schema:
        maxLength: 128
        minLength: 36
        type: string
    TestIdParam:
      description: Test ID returned from the Test API to query.
      in: path
      name: test_id
      required: true
      schema:
        format: uuid
        type: string
    io.snyk.api.request.SnykApiRequest.request_id:
      description: 'A unique ID assigned to each API request, for tracing and troubleshooting.


        Snyk clients can optionally provide this ID.'
      in: header
      name: snyk-request-id
      schema:
        format: uuid
        type: string
    io.snyk.api.request.SnykApiRequest.version:
      description: The API version requested.
      explode: false
      in: query
      name: version
      required: true
      schema:
        type: string
  schemas:
    SuppressionStatus:
      description: Status of a suppression on a finding.
      enum:
      - ignored
      - pending_ignore_approval
      - other
      type: string
    Diff:
      description: 'Fix suggestions in the unified diff format that introduce code changes

        to remediate the vulnerability.'
      example:
        format: diff
        suggestions:
        - diff: '--- a/auth.ts

            +++ b/auth.ts

            @@ -1,1 +1,1 @@

            -eval(userInput)

            +safeEval(userInput)

            '
          external_id: 550e8400-e29b-41d4-a716-446655440000
          rank: 1
        - diff: '--- a/auth.ts

            +++ b/auth.ts

            @@ -1,1 +1,1 @@

            -password === input

            +bcrypt.compare(input, password)

            '
          external_id: 550e8400-e29b-41d4-a716-446655440001
          rank: 2
      properties:
        format:
          enum:
          - diff
          type: string
        suggestions:
          description: 'Alternative suggestions - choose one to fix the vulnerability.

            The ''rank'' field signals the relative confidence in each one.'
          items:
            $ref: '#/components/schemas/DiffSuggestion'
          type: array
      required:
      - format
      - suggestions
      type: object
    FindingLocation:
      description: Location within an Subject's contents where the finding was discovered.
      discriminator:
        mapping:
          other: '#/components/schemas/OtherLocation'
          package: '#/components/schemas/PackageLocation'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/PackageLocation'
      - description: 'Source file location.


          Finding types: SCA, SAST'
        example:
          file_path: package.json
          from_column: 12
          from_line: 24
          to_column: 36
          to_line: 24
          type: source
        properties:
          file_path:
            description: File path for the code snippet.
            type: string
          from_column:
            description: Column on which the snippet starts.
            type: integer
          from_line:
            description: Line in the file where the code snippet starts.
            type: integer
          to_column:
            description: Column at which the code snippet ends.
            type: integer
          to_line:
            description: Line on which the code snippet ends.
            type: integer
          type:
            enum:
            - source
            type: string
        required:
        - type
        - file_path
        - from_line
        type: object
      - $ref: '#/components/schemas/OtherLocation'
    DependencyPathEvidence:
      description: 'Dependency path to a software component within an SBOM dependency graph.


        Finding types: SCA'
      properties:
        path:
          description: 'Series of component identifiers starting from the top-level component tested,

            and ending in the vulnerable software component.


            The identifiers are domain-specific and determined by the test subject.'
          items:
            $ref: '#/components/schemas/Package'
          type: array
        source:
          enum:
          - dependency_path
          type: string
      required:
      - source
      - path
      type: object
    UpgradePackageAdvice:
      description: Upgrade a package from one version to another.
      example:
        format: upgrade_package_advice
        package_name: lodash
        upgrade_paths:
        - dependency_path:
          - name: lodash
            version: 2.1.1
          - name: minimist
            version: 4.7.6
          is_drop: false
      properties:
        format:
          enum:
          - upgrade_package_advice
          type: string
        package_name:
          description: The package that's receiving an upgrade to fix this vulnerability
          type: string
        upgrade_paths:
          description: 'Upgrading a package may lead to one or more paths to change. These paths are modelled as evidence

            in DependencyPathEvidence.


            Ultimately upgradePaths illustrates the minimum version upgrades that need to happen to apply this action.'
          items:
            $ref: '#/components/schemas/UpgradePath'
          type: array
      required:
      - format
      - package_name
      - upgrade_paths
      type: object
    io.snyk.api.common.ErrorLink:
      additionalProperties:
        $ref: '#/components/schemas/io.snyk.api.common.LinkProperty'
      description: A link that leads to further details about this particular occurrance of the problem.
      properties:
        about:
          $ref: '#/components/schemas/io.snyk.api.common.LinkProperty'
      type: object
    io.snyk.api.common.Error:
      properties:
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        id:
          description: A unique identifier for this particular occurrence of the problem.
          format: uuid
          type: string
        links:
          $ref: '#/components/schemas/io.snyk.api.common.ErrorLink'
        meta:
          type: object
        source:
          properties:
            parameter:
              type: string
            pointer:
              type: string
          type: object
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          pattern: ^[45]\d\d$
          type: string
        title:
          description: A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
      required:
      - status
      - detail
      type: object
    ReachablePath:
      description: ReachablePath represents the paths to a vulnerable function.
      properties:
        call_paths:
          description: Paths in code bundle that call the vulnerable function.
          items:
            type: string
          type: array
        function_name:
          description: Vulnerable function name.
          type: string
        location:
          allOf:
          - $ref: '#/components/schemas/FileRegion'
          description: Location in a file where the vulnerability can be found.
      required:
      - function_name
      - call_paths
      type: object
    ExecutionFlowEvidence:
      description: Indicate a program flow of execution as additional evidence for the finding.
      properties:
        flow:
          description: 'Sequence of locations within this flow of execution.


            For example, a sequence of locations connecting the "source" location

            where input data is obtained, to a "sink" location where it is used.'
          items:
            $ref: '#/components/schemas/FileRegion'
          minItems: 1
          type: array
        source:
          enum:
          - execution_flow
          type: string
      required:
      - source
      - flow
      type: object
    Evidence:
      description: 'Supporting evidence for (rather than representative of) the finding in other

        security domains and systems, lacking a well-known identifier.


        More detailed attributes may also be included inline, especially when this

        information is not yet generally available in a well-known public APIs.


        Examples include:

        - Detailed enumeration of dependency paths

        - Execution flows leading to a code rule violation'
      discriminator:
        mapping:
          dependency_path: '#/components/schemas/DependencyPathEvidence'
          execution_flow: '#/components/schemas/ExecutionFlowEvidence'
          other: '#/components/schemas/OtherEvidence'
          reachability: '#/components/schemas/ReachabilityEvidence'
        propertyName: source
      oneOf:
      - $ref: '#/components/schemas/DependencyPathEvidence'
      - $ref: '#/components/schemas/ExecutionFlowEvidence'
      - $ref: '#/components/schemas/ReachabilityEvidence'
      - $ref: '#/components/schemas/OtherEvidence'
    Rating:
      description: Rating represents qualitative metrics on a finding.
      properties:
        severity:
          allOf:
          - $ref: '#/components/schemas/Severity'
          description: Severity level of the finding.
      required:
      - severity
      type: object
    String256:
      maxLength: 256
      type: string
    Severity:
      description: Indicate the severity of a finding discovered by a Test.
      enum:
      - critical
      - high
      - medium
      - low
      - none
      - other
      type: string
    io.snyk.api.common.ErrorDocument:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/io.snyk.api.common.Error'
          minItems: 1
          type: array
        jsonapi:
          $ref: '#/components/schemas/io.snyk.api.common.JsonApi'
      required:
      - jsonapi
      - errors
      type: object
    io.snyk.api.common.LinkObject:
      properties:
        href:
          $ref: '#/components/schemas/io.snyk.api.common.LinkString'
        meta:
          $ref: '#/components/schemas/io.snyk.api.common.Meta'
      required:
      - href
      type: object
    OtherLocation:
      description: 'Finding locations which this API version is not capable of expressing.


        This location may be available in a newer version of this API.'
      properties:
        type:
          enum:
          - other
          type: string
      required:
      - type
      type: object
    Uuid:
      format: uuid
      type: string
    FindingType:
      description: Type of Finding which was discovered.
      enum:
      - sca
      - sast
      - dast
      - other
      - config
      - secret
      - secrets
      type: string
    io.snyk.api.common.LinkString:
      format: uri
      type: string
    FileRegion:
      description: FileRegion models a location where vulnerable code is found.
      properties:
        file_path:
          description: File path for the code snippet.
          type: string
        from_column:
          description: Column on which the snippet starts.
          type: integer
        from_line:
          description: Line in the file where the code snippet starts.
          type: integer
        to_column:
          description: Column at which the code snippet ends.
          type: integer
        to_line:
          description: Line on which the code snippet ends.
          type: integer
      required:
      - file_path
      - from_line
      type: object
    FindingData:
      description: FindingData represents a Finding resource object.
      properties:
        attributes:
          allOf:
          - $ref: '#/components/schemas/FindingAttributes'
          readOnly: true
        id:
          format: uuid
          readOnly: true
          type: string
        links:
          description: 'Links to external resources outside this API.


            Because these are not REST API resources, they are expressed here as links,

            rather than as relationships.'
          properties:
            snyk_advisory:
              allOf:
              - $ref: '#/components/schemas/io.snyk.api.common.LinkProperty'
              description: 'Link to Snyk''s vulnerability advisory for more information on the

                finding, if applicable.'
              example: https://security.snyk.io/vuln/SNYK-JAVA-ORGAPACHELOGGINGLOG4J-2314720
            snyk_learn:
              allOf:
              - $ref: '#/components/schemas/io.snyk.api.common.LinkProperty'
              description: Link to a Snyk Learn lesson relevant to the finding, if applicable.
              example: https://learn.snyk.io/lesson/csrf-attack/
          type: object
        relationships:
          properties:
            asset:
              description: Originating asset in which this finding was discovered.
              properties:
                data:
                  properties:
                    id:
                      format: uuid
                      type: string
                    type:
                      pattern: ^[a-z][a-z0-9]*(_[a-z][a-z0-9]*)*$
                      type: string
                  required:
                  - type
                  - id
                  type: object
                links:
                  $ref: '#/components/schemas/io.snyk.api.common.RelatedLink'
                meta:
                  $ref: '#/components/schemas/io.snyk.api.common.Meta'
              required:
              - links
              type: object
            fix:
              description: Fix for this finding, it comes expanded with all data preloaded
              properties:
                data:
                  properties:
                    attributes:
                      allOf:
                      - $ref: '#/components/schemas/FixAttributes'
                      description: 'Inlined attributes included in the relationship, if it is expanded.


                        Expansion is a Snyk variation on JSON API. See

                        https://snyk.roadie.so/docs/default/component/sweater-comb/standards/rest/#expansion'
                    id:
                      format: uuid
                      type: string
                    type:
                      pattern: ^[a-z][a-z0-9]*(_[a-z][a-z0-9]*)*$
                      type: string
                  required:
                  - type
                  - id
                  type: object
              type: object
            org:
              description: Snyk organization scope in which the finding was discovered.
              properties:
                data:
                  properties:
                    id:
                      format: uuid
                      type: string
                    type:
                      pattern: ^[a-z][a-z0-9]*(_[a-z][a-z0-9]*)*$
                      type: string
                  required:
                  - type
                  - id
                  type: object
              type: object
            policy:
              description: Relate to the policy or policies applied to this finding.
              properties:
                data:
                  properties:
                    attributes:
                      allOf:
                      - properties:
                          policies:
                            items:
                              properties:
                                applied_policy:
                                  anyOf:
                                  - properties:
                                      action_type:
                                        enum:
                                        - severity-change
                                        type: string
                                      policy_ref:
                                        description: Reference to a policy, serving as a container for a set of policy-rules and can be owned by the group or the org.
                                        properties:
                                          id:
                                            format: uuid
                                            type: string
                                          owner:
                                            enum:
                                            - org
                                            - group
                                            type: string
                                        required:
                                        - id
                                        - owner
                                        type: object
                                      rule:
                                        description: 'A policy rule is the central entity of a policy, including an action as well as conditions

                                          when this policy applies.

                                          Only a subset of fields are included, for more details see the API documentation

                                          https://apidocs.snyk.io/?version=2024-10-15#get-/orgs/-org_id-/policies/-policy_id-'
                                        properties:
                                          created:
                                            format: date-time
                                            type: string
                                          id:
                                            format: uuid
                                            type: string
                                          modified:
                                            format: date-time
                                            type: string
                                          name:
                                            type: string
                                          review:
                                            enum:
                                            - approved
                                            - rejected
                                            - pending
                                            - cancelled
                                            - not-required
                                            - unknown
                                            type: string
                                        required:
                                        - id
                                        - name
                                        - modified
                                        - created
                                        - review
                                        type: object
                                      severity_change:
                                        properties:
                                          new_severity:
                                            description: Indicate the severity of a finding discovered by a Test.
                                            enum:
                                            - critical
                                            - high
                                            - medium
                                            - low
                                            - none
                                            - other
                                            type: string
                                          original_severity:
                                            description: Indicate the severity of a finding discovered by a Test.
                                            enum:
                                            - critical
                                            - high
                                            - medium
                                            - low
                                            - none
                                            - other
                                            type: string
                                        required:
                                        - original_severity
                                        - new_severity
                                        type: object
                                    required:
                                    - action_type
                                    - policy_ref
                                    - rule
                                    - severity_change
                                    type: object
                                  - properties:
                                      action_type:
                                        enum:
                                        - ignore
                                        type: string
                                      ignore:
                                        properties:
                                          created:
                                            format: date-time
                                            type: string
                                          disregard_if_fixable:
                                            description: Disregards the policy if set to true and the finding this policy is applied to is fixable
                                            type: boolean
                                          expires:
                                            format: date-time
                                            type: string
                                          ignored_by:
                                            properties:
                                              email:
                                                description: Email of the user who created the ignore
                                                type: string
                                              id:
                                                description: User ID of the author of the ignore
                                                format: uuid
                                                type: string
                                              name:
                                                description: Name of the user who created the ignore
                                                type: string
                                            required:
                                            - id
                                            - name
                                            type: object
                                          path:
                                            items:
                                              type: string
                                            maxItems: 10
                                            type: array
                                          reason:
                                            type: string
                                          reason_type:
                                            enum:
                                            - wont-fix
                                            - not-vulnerable
                                            - temporary-ignore
                                            type: string
                                          source:
                                            type: string
                                        required:
                                        - reason
                                        - source
                                        type: object
                                      policy_ref:
                                        description: Reference to a policy, serving as a container for a set of policy-rules and can be owned by the group or the org.
                                        properties:
                                          id:
                                            format: uuid
                                            type: string
                                          owner:
                                            enum:
                                            - org
                                            - group
                                            type: string
                                        required:
                                        - id
                                        - owner
                                        type: object
                                      rule:
                                        description: 'A policy rule is the central entity of a policy, including an action as well as conditions

                                          when this policy applies.

                                          Only a subset of fields are included, for more details see the API documentation

                                          https://apidocs.snyk.io/?version=2024-10-15#get-/orgs/-org_id-/policies/-policy_id-'
                                        properties:
                                          created:
                                            format: date-time
                                            type: string
                                          id:
                                            format: uuid
                                            type: string
                                          modified:
                                            format: date-time
                                            type: string
                                          name:
                                            type: string
                                          review:
                                            enum:
                                            - approved
                                            - rejected
                                            - pending
                                            - cancelled
                                            - not-required
                                            - unknown
                                            type: string
                                        required:
                                        - id
                                        - name
                                        - modified
                                        - created
                                        - review
                                        type: object
                                    required:
                                    - action_type
         

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/snyk/refs/heads/main/openapi/snyk-findings-api-openapi.yml