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

# List files in a sandbox repository

> Returns the immediate read-only repository tree. Select repo when the sandbox contains more than one repository.



## OpenAPI

````yaml /openapi.json get /api/public/v1/sandboxes/{sandboxId}/files/tree
openapi: 3.1.0
info:
  title: Sparkles Sandbox API
  version: 1.0.0
  description: Create coding sandboxes, stream their work, and control their lifecycle.
servers:
  - url: https://sparkles.dev
security: []
paths:
  /api/public/v1/sandboxes/{sandboxId}/files/tree:
    get:
      tags:
        - sandbox files
      summary: List files in a sandbox repository
      description: >-
        Returns the immediate read-only repository tree. Select repo when the
        sandbox contains more than one repository.
      operationId: listSandboxFiles
      parameters:
        - in: path
          name: sandboxId
          schema:
            type: string
            pattern: ^c_[a-z2-9]{12}$
          required: true
        - in: query
          name: directory
          schema:
            default: ''
            type: string
            maxLength: 1000
        - in: query
          name: repo
          schema:
            type: string
            maxLength: 201
            pattern: ^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$
      responses:
        '200':
          description: The requested repository directory
          content:
            application/json:
              schema:
                type: object
                properties:
                  directory:
                    type: string
                  entries:
                    type: array
                    items:
                      type: object
                      properties:
                        additions:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        deletions:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        depth:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        kind:
                          type: string
                          enum:
                            - directory
                            - file
                        mtimeMs:
                          anyOf:
                            - type: number
                              minimum: 0
                            - type: 'null'
                        name:
                          type: string
                        path:
                          type: string
                        previousPath:
                          type:
                            - string
                            - 'null'
                        size:
                          anyOf:
                            - type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            - type: 'null'
                        status:
                          anyOf:
                            - type: string
                              enum:
                                - added
                                - deleted
                                - modified
                                - renamed
                                - untracked
                            - type: 'null'
                      required:
                        - additions
                        - deletions
                        - kind
                        - name
                        - path
                        - previousPath
                        - status
                      additionalProperties: false
                  partialWarnings:
                    type: array
                    items:
                      type: string
                  scope:
                    type: string
                    const: all
                required:
                  - directory
                  - entries
                  - partialWarnings
                  - scope
                additionalProperties: false
        '400':
          description: The directory or repository selector failed validation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Missing, malformed, revoked, or otherwise invalid API key
          headers:
            WWW-Authenticate:
              required: true
              description: Bearer authentication challenge for the Sparkles Sandbox API
              schema:
                type: string
                description: Bearer authentication challenge for the Sparkles Sandbox API
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '403':
          description: >-
            The API key lacks the sandboxes scope or its user is no longer an
            active organization member
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: Sandbox, repository, file, or directory not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '409':
          description: Sandbox files are not available yet
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '413':
          description: The requested file operation exceeded its size limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '422':
          description: The repository helper rejected the request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '429':
          description: The API key exceeded its distributed per-minute request limit
          headers:
            Retry-After:
              required: true
              description: Seconds until another request may be made
              schema:
                type: string
                pattern: ^\d+$
                description: Seconds until another request may be made
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: The request could not be completed because of an internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: spk_live_…
      description: >-
        Long-lived opaque API key minted by an approved user at /api. The secret
        is shown once, stored only as a SHA-256 digest, and disabled immediately
        when either the key or its API access grant is revoked.

````