> ## 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.

# List repositories.

> # Access control rules

- The requester must have access to the repository for it to be listed.



## OpenAPI

````yaml GET /api/v0/repositories
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:
    get:
      tags:
        - repositories
      summary: List repositories.
      description: |-
        # Access control rules

        - The requester must have access to the repository for it to be listed.
      operationId: list_repos
      parameters:
        - name: kind
          in: query
          description: >-
            Kind of repository to return.


            This returns an error if the repository kind is not public.


            Defaults to returning public repositories, currently competitions
            and

            bounties.
          required: false
          schema:
            type:
              - array
              - 'null'
            items:
              $ref: '#/components/schemas/RepositoryKind'
        - name: q
          in: query
          description: |-
            Search the company name, opportunity name and instructions.

            Defaults to no filtering.
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status
          in: query
          description: |-
            Filter based on repository statuses.

            Defaults to no filtering.
          required: false
          schema:
            type:
              - array
              - 'null'
            items:
              $ref: '#/components/schemas/RepositoryStatus'
        - name: role
          in: query
          description: |-
            Filter based on the role the user has in the repository.

            NOTE: not used in listing public repositories.

            Defaults to no filtering.
          required: false
          schema:
            oneOf:
              - type: 'null'
              - $ref: '#/components/schemas/RepositoryRole'
      responses:
        '200':
          description: List of repositories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repository'
        '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'
        '500':
          description: Error accessing repos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CantinaError'
components:
  schemas:
    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
    Repository:
      type: object
      required:
        - id
        - name
        - engagementId
        - company
        - gitRepoUrl
        - commitHash
        - kind
        - status
        - currencyCode
        - showAllFindings
        - publicMetadata
        - kycRequired
        - totalFindings
        - accessibleFindings
        - aiStatus
        - createdAt
        - createdBy
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        engagementId:
          type: string
          format: uuid
        company:
          $ref: '#/components/schemas/RepositoryCompany'
        readmePath:
          type:
            - string
            - 'null'
          description: Path to the main readme file.
        gitRepoUrl:
          type: string
        commitHash:
          type: string
        timeframe:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RangeFromDateTime'
        kind:
          $ref: '#/components/schemas/RepositoryKind'
        status:
          $ref: '#/components/schemas/RepositoryStatus'
        currencyCode:
          type: string
          description: >-
            Currency for `total_reward_pot`, `primary_pot`, `additional_pot` and
            all

            currencies in `additional_pot_split`.


            Currently this defaults to USDC.
        totalRewardPot:
          type:
            - string
            - 'null'
        primaryPot:
          type:
            - string
            - 'null'
          description: |-
            Primary pot value.
            *Admin only*.
        additionalPot:
          type:
            - string
            - 'null'
          description: |-
            Sum of all the additional rewards, excluding tips.
            *Admin only*.
        additionalPotSplit:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/AdditionalReward'
          description: |-
            Split of the additional pot.
            *Admin only*.
        stakeAmount:
          type:
            - string
            - 'null'
          description: |-
            Stake amount for escalations.

            NOTE: stakes are always in USDC.

            If not set it means escalations don't require staking.
        submissionFee:
          type:
            - string
            - 'null'
          description: |-
            Amount required for submission a new finding.
            for escalations.

            NOTE: fees are always in USDC.

            If not set it means submissions are free.
        assetGroups:
          type: array
          items:
            $ref: '#/components/schemas/AssetGroup'
          description: Groups of assets.
        pointCalculation:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PointCalculationFunction'
              description: |-
                Point calculation set for the given repository
                *Admin only*.
        instructions:
          type:
            - string
            - 'null'
        allowedSeverities:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/FindingSeverity'
          description: >-
            Allowed finding severties for findings.


            If this is undefined all severties are allowed. Otherwise only the

            severties in the list are allowed to be used when creating or
            updating

            findings.
        consideredSeverities:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/FindingSeverity'
          description: |-
            Finding severities that are considered to be eligible for a reward.

            If this is null all severities are considered, otherwise on only
            severities in the list are considered for a reward.
        allowedLabels:
          type: array
          items:
            $ref: '#/components/schemas/FindingLabel'
        showAllFindings:
          type: boolean
          description: Show all findings to researchers during judging and escalations
        publicMetadata:
          type: boolean
          description: |-
            Show a private repository's (competition or bounty) metadata.

            This is only relevant for private competitions and bounties.
        kycRequired:
          type: boolean
          description: Require reviewers to KYC before joining.
        companyUserAccess:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RepositoryCompanyUserAccess'
              description: User access level for the repository.
        requiredCtfAddress:
          type:
            - string
            - 'null'
          description: Require reviewers to have a CTF address set before joining.
        totalFindings:
          type: integer
          format: int32
          description: Total number of findings.
        accessibleFindings:
          type: integer
          format: int32
          description: Number of findings visible to the user.
        aiStatus:
          $ref: '#/components/schemas/RepositoryAiStatus'
          description: The AI status of the repository.
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
          format: uuid
        capabilities:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RepositoryCapabilities'
              description: |-
                Provide a set of capabilities to simplify the
                frontend behaviour logic.

                It is populated only by get_repo
        safeHarbor:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SafeHarbor'
              description: >-
                Specifies a Safe Harbor: a set of instructions, assets, return
                addresses, etc. that can

                be used by white hat security researchers to return assets
                received from exploitation of

                discovered vulnerabilities to ensure their findings.
    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.
    RepositoryCompany:
      type: object
      description: '[`Company`] information in the context of a [`Repository`].'
      required:
        - id
        - name
        - handle
        - logo
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        handle:
          type: string
        logo:
          type: string
        website:
          type:
            - string
            - 'null'
        github:
          type:
            - string
            - 'null'
        twitter:
          type:
            - string
            - 'null'
    RangeFromDateTime:
      type: object
      description: Represent a range where the start is always set but the end is optional.
      required:
        - start
      properties:
        start:
          type: string
          format: date-time
        end:
          type:
            - string
            - 'null'
          format: date-time
    AdditionalReward:
      type: object
      description: Additional reward in a [`Repository`].
      required:
        - teamId
        - amount
        - isTip
      properties:
        teamId:
          type: string
          format: uuid
          description: The repository team to award it to.
        amount:
          type: string
          description: Amount of the reward.
        isTip:
          type: boolean
          description: |-
            Whether or not it's considered a tip.
            If so, it will be exlcuded from the `additional_pot` value.
    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'
    PointCalculationFunction:
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
    FindingSeverity:
      type: string
      description: Severity of a [`Finding`].
      enum:
        - critical
        - high
        - medium
        - low
        - informational
        - gas_optimization
    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
    RepositoryCompanyUserAccess:
      type: string
      description: Company user access level for a repository.
      enum:
        - open
        - restricted
    RepositoryAiStatus:
      type: string
      enum:
        - inactive
        - in_progress
        - active
    RepositoryCapabilities:
      type: object
      required:
        - labelEdit
        - labelEditReviewerVisibility
        - labelStartEscalation
      properties:
        labelEdit:
          type: boolean
        labelEditReviewerVisibility:
          type: boolean
        labelStartEscalation:
          type: boolean
    SafeHarbor:
      type: object
      required:
        - id
        - description
        - reward
        - returnAddresses
        - assets
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        cap:
          type:
            - string
            - 'null'
        reward:
          type: string
        returnAddresses:
          type: array
          items:
            $ref: '#/components/schemas/SafeHarborReturnAddress'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/SafeHarborAsset'
    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
    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'
    ColorLabel:
      type: string
      description: The color of a label
      enum:
        - red
        - yellow
        - purple
        - violet
        - blue
        - green
        - grey
    SafeHarborReturnAddress:
      type: object
      required:
        - id
        - address
        - chain
      properties:
        id:
          type: string
          format: uuid
        address:
          type: string
        chain:
          $ref: '#/components/schemas/SafeHarborAddressChain'
    SafeHarborAsset:
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
    SafeHarborAddressChain:
      type: string
      enum:
        - ethereum
        - bsc
        - polygon
        - arbitrum
        - optimism
        - base
        - avalanche_c
        - polygon_zk_evm
        - gnosis
        - zk_sync

````