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

# Get a finding in a repository.

> # Access control rules

- The requester must have access to the repository.
- Reviewers have access to the finding they and their team made.
- Clients, judges, triagers and admins have access to all findings.

# Additional data

For bounty repositories, admins, clients, and triagers will also receive
the researcher's bounty finding stats (spam, rejected, confirmed counts
and number of bounties participated).



## OpenAPI

````yaml GET /api/v0/repositories/{repo_id}/findings/{finding_ref}
openapi: 3.1.0
info:
  title: Cantina Client API
  description: >-
    Endpoints available to client organizations. For an overview and
    authentication, see
    https://docs.cantina.xyz/for-organizations/getting-started/api-access.
  license:
    name: Cantina
    identifier: Cantina
  version: 0.1.0
servers: []
security: []
paths:
  /api/v0/repositories/{repo_id}/findings/{finding_ref}:
    get:
      tags:
        - repositories
      summary: Get a finding in a repository.
      description: |-
        # Access control rules

        - The requester must have access to the repository.
        - Reviewers have access to the finding they and their team made.
        - Clients, judges, triagers and admins have access to all findings.

        # Additional data

        For bounty repositories, admins, clients, and triagers will also receive
        the researcher's bounty finding stats (spam, rejected, confirmed counts
        and number of bounties participated).
      operationId: get_finding
      parameters:
        - name: repo_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: finding_ref
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/FindingRef'
      responses:
        '200':
          description: Finding with optional researcher stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindingWithStats'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CantinaError'
        '401':
          description: Access not authorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CantinaError'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CantinaError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CantinaError'
        '500':
          description: Error accessing finding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CantinaError'
components:
  schemas:
    FindingRef:
      oneOf:
        - type: string
          format: uuid
          description: Finding id.
        - type: integer
          format: int32
          description: Finding number.
      description: Reference to a finding, either a finding id or finding number.
    FindingWithStats:
      allOf:
        - $ref: '#/components/schemas/Finding'
        - type: object
          properties:
            researcherStats:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/ResearcherBountyFindingStats'
    CantinaError:
      type: object
      description: Error returned by the Cantina API.
      required:
        - type
        - msg
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        msg:
          type: string
          description: Error message for the user.
    Finding:
      type: object
      description: Finding within a respository.
      required:
        - id
        - number
        - attributedTo
        - title
        - description
        - status
        - severity
        - relatedFiles
        - createdBy
        - createdAt
        - lastUpdatedAt
        - locked
        - hasUnreadComments
        - unreadCommentsNumber
      properties:
        id:
          type: string
          format: uuid
        number:
          type: integer
          format: int32
        repository:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FindingRepository'
              description: Only returned by `list_all_findings`.
        company:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FindingCompany'
              description: Only returned by `list_all_findings`.
        attributedTo:
          type: string
          format: uuid
          description: Team id.
        title:
          type: string
        description:
          type: string
        reward:
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/FindingStatus'
        fixedBy:
          type: array
          items:
            type: string
        duplicateOf:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FindingDuplicateOf'
              description: The root finding this finding is a duplicate of.
        duplicates:
          type: array
          items:
            $ref: '#/components/schemas/FindingDuplicateOf'
          description: |-
            All findings that are a duplicate of this finding.

            For findings that have no duplicates, this will be empty.
        duplicateGroup:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/DuplicateFindingGroup'
              description: Only returned for admins, judges and triagers.
        severity:
          $ref: '#/components/schemas/FindingSeverity'
        likelihood:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FindingLikelihood'
        impact:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FindingImpact'
        quality:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FindingQuality'
              description: Only returned for admins, judges and triagers.
        category:
          type:
            - string
            - 'null'
          description: Only returned for admins.
        relatedFiles:
          type: array
          items:
            $ref: '#/components/schemas/FindingRelatedFile'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/FindingLabel'
        assignedTo:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RepositoryUser'
              description: User assigned to the finding.
        assetGroup:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AssetGroup'
        createdBy:
          $ref: '#/components/schemas/RepositoryUser'
        createdAt:
          type: string
          format: date-time
        lastUpdatedAt:
          type: string
          format: date-time
        locked:
          type: boolean
        lastCommentAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of the most recent comment on this finding, if any.
        hasUnreadComments:
          type: boolean
          description: Whether this finding has comments unread by the current user.
        unreadCommentsNumber:
          type: integer
          format: int32
          description: >-
            The number of comments this finding has that are unread by the
            current user.
        safeHarborAssets:
          type: array
          items:
            $ref: '#/components/schemas/SafeHarborAsset'
        note:
          type:
            - string
            - 'null'
          description: Note field for additional finding information.
        paymentId:
          type:
            - string
            - 'null'
          format: uuid
          description: Payment ID linked to this finding, if any.
        paymentStatus:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PaymentStatus'
              description: Status of the payment linked to this finding, if any.
    ResearcherBountyFindingStats:
      type: object
      required:
        - userId
        - spamCount
        - rejectedCount
        - confirmedCount
        - bountiesParticipated
      properties:
        userId:
          type: string
          format: uuid
        spamCount:
          type: integer
          format: int32
        rejectedCount:
          type: integer
          format: int32
        confirmedCount:
          type: integer
          format: int32
        bountiesParticipated:
          type: integer
          format: int32
    ErrorType:
      type: string
      description: Type of error.
      enum:
        - email_not_verified
        - auth_invalid
        - auth_expired
        - auth_token_missing
        - auth_id_missing
        - invalid_password
        - disabled_user
        - tc_not_accepted
        - evicted
        - unauthorized
        - bad_request
        - not_found
        - forbidden
        - gone
        - payload_too_large
        - service_unavailable
        - internal_error
    FindingRepository:
      type: object
      description: Minimal information of a [`Repository`] attached to a [`Finding`].
      required:
        - id
        - name
        - kind
        - status
        - userRole
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        kind:
          $ref: '#/components/schemas/RepositoryKind'
        status:
          $ref: '#/components/schemas/RepositoryStatus'
        allowedSeverities:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/FindingSeverity'
        userRole:
          $ref: '#/components/schemas/RepositoryRole'
          description: Role of the user access in the finding in the repository.
    FindingCompany:
      type: object
      description: Minimal information of a [`Company`] attached to a [`Finding`].
      required:
        - id
        - handle
      properties:
        id:
          type: string
          format: uuid
        handle:
          type: string
    FindingStatus:
      type: string
      description: |-
        Status of a [`Finding`].
        Note that the `in_review` status is only applicable within bounties.
      enum:
        - new
        - in_review
        - disputed
        - rejected
        - spam
        - duplicate
        - confirmed
        - acknowledged
        - fixed
        - withdrawn
    FindingDuplicateOf:
      type: object
      description: >-
        Partial [`Finding`] used in [`Finding::duplicate_of`] and
        [`Finding::duplicates`].
      required:
        - id
        - number
        - status
      properties:
        id:
          type: string
          format: uuid
        number:
          type: integer
          format: int32
        title:
          type:
            - string
            - 'null'
          description: >-
            This may be null in case the user doesn't have access to the finding

            yet. For example reviewers in live competitions (without access to
            the

            root/duplicate finding).
        status:
          $ref: '#/components/schemas/FindingStatus'
    DuplicateFindingGroup:
      type: object
      required:
        - description
        - findings
      properties:
        description:
          type: string
          description: The description of the group of duplicated findings.
        findings:
          type: array
          items:
            $ref: '#/components/schemas/FindingDuplicateOf'
          description: The group of duplicated findings.
    FindingSeverity:
      type: string
      description: Severity of a [`Finding`].
      enum:
        - critical
        - high
        - medium
        - low
        - informational
        - gas_optimization
    FindingLikelihood:
      type: string
      description: Likelihood of a [`Finding`].
      enum:
        - high
        - medium
        - low
    FindingImpact:
      type: string
      description: Impact of a [`Finding`].
      enum:
        - high
        - medium
        - low
    FindingQuality:
      type: string
      description: Quality of a [`Finding`].
      enum:
        - high
        - medium
        - low
    FindingRelatedFile:
      type: object
      required:
        - id
        - path
        - lines
      properties:
        id:
          type: string
          format: uuid
        path:
          type: string
        language:
          type:
            - string
            - 'null'
        lines:
          $ref: '#/components/schemas/InclusiveRangeInt'
          description: The line(s) refered to in the comment.
        relevantContent:
          type:
            - string
            - 'null'
          description: >-
            Content of the file that is relevant to the finding, i.e. the
            `lines` of

            the content.


            # Notes


            This may be null if the `lines` are invalid (e.g. they go beyond the

            amount of lines) or if the file is binary.
    FindingLabel:
      type: object
      description: Label on a finding.
      required:
        - id
        - name
        - color
        - isSystem
        - reviewerRead
        - reviewerUse
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        color:
          $ref: '#/components/schemas/ColorLabel'
        isSystem:
          type: boolean
          description: |-
            Label is a system label, used in all repositories.
            All users can view this label.
        reviewerRead:
          type: boolean
          description: |-
            Reviewer can view the label when set on a finding.
            Note that admins, clients, judges and triagers can view all labels.
        reviewerUse:
          type: boolean
          description: >-
            Reviewer can set or remove the label from a finding.

            Note that admins, clients, judges and triagers can set and remove
            all

            labels.
        archivedAt:
          type:
            - string
            - 'null'
          format: date-time
    RepositoryUser:
      type: object
      description: User data in the context of a repository.
      required:
        - userId
        - name
        - username
        - repositoryRole
        - avatar
        - isBot
        - createdAt
      properties:
        userId:
          type: string
          format: uuid
          description: User id, not to be confused with a client id.
        name:
          type: string
        username:
          type: string
        teamId:
          type:
            - string
            - 'null'
          format: uuid
          description: |-
            Id of the team the reviewer is a part of.

            For non-reviewers, this will be null.
        pingsLeft:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Number of times the reviewer can ping the client.


            Visible to admins, company users, and reviewers only when viewing
            their own info.


            For non-reviewers, this will be null.
        reputation:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Reputation of an auditor, always in the range of `0..=100`.


            Visible to admins, clients, judges and triagers only. Only returned
            in the

            finding's creator field (`Finding.created_by.reputation`), not in
            other

            places.


            For non-reviewers, this will be null.
        repositoryRole:
          $ref: '#/components/schemas/RepositoryRole'
        avatar:
          type: string
        isBot:
          type: boolean
        createdAt:
          type: string
          format: date-time
        disabledAt:
          type:
            - string
            - 'null'
          format: date-time
          description: User is disabled and doesn't have access to Cantina any more.
        deletedFromRepoAt:
          type:
            - string
            - 'null'
          format: date-time
          description: User is deleted from the repository.
    AssetGroup:
      type: object
      description: Group of [`Asset`]s.
      required:
        - id
        - name
        - description
        - outOfScope
        - rewards
        - assets
        - subGroups
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        outOfScope:
          type: boolean
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/AssetGroupReward'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
        subGroups:
          type: array
          items:
            $ref: '#/components/schemas/AssetSubGroup'
    SafeHarborAsset:
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
    PaymentStatus:
      type: string
      enum:
        - planned
        - scheduled
        - submitted
        - disputed
        - executed
        - rejected
        - failed
        - cancelled
    RepositoryKind:
      type: string
      enum:
        - scoping
        - collaborative_review
        - private_contest
        - public_contest
        - private_bounty
        - public_bounty
    RepositoryStatus:
      type: string
      description: Status of a repository.
      enum:
        - draft
        - upcoming
        - live
        - judging
        - escalations
        - escalations_ended
        - complete
        - published
    RepositoryRole:
      type: string
      description: Role of a user in the context of a repository.
      enum:
        - client
        - reviewer
        - judge
        - triager
        - admin
    InclusiveRangeInt:
      type: object
      description: >-
        Represent a range where both the start and end are included in the
        range.
      required:
        - start
        - end
      properties:
        start:
          type: integer
          format: int32
        end:
          type: integer
          format: int32
    ColorLabel:
      type: string
      description: The color of a label
      enum:
        - red
        - yellow
        - purple
        - violet
        - blue
        - green
        - grey
    AssetGroupReward:
      type: object
      description: Reward for an [`AssetGroup`].
      required:
        - severity
      properties:
        severity:
          $ref: '#/components/schemas/FindingSeverity'
        minReward:
          type:
            - string
            - 'null'
        maxReward:
          type:
            - string
            - 'null'
    Asset:
      type: object
      description: Asset description.
      required:
        - id
        - name
        - description
        - reference
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        reference:
          type: string
          description: >-
            Reference to where the asset is located. For example a URL to a
            website

            or an address of a contract.
    AssetSubGroup:
      type: object
      description: Subgroup of an [`AssetGroup`]s.
      required:
        - id
        - name
        - assets
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'

````