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

# Upload Files

> Upload one or more files to the authenticated account's sandbox GitHub repository. Accepts an array of file URLs and commits each file to the specified directory path within the repository. Supports submodule resolution — if the target path falls within a git submodule, the file is committed to the submodule's repository. Authentication is handled via the x-api-key header or Authorization Bearer token.



## OpenAPI

````yaml api-reference/openapi/content.json POST /api/sandboxes/files
openapi: 3.1.0
info:
  title: Recoup API - Content
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/sandboxes/files:
    post:
      description: >-
        Upload one or more files to the authenticated account's sandbox GitHub
        repository. Accepts an array of file URLs and commits each file to the
        specified directory path within the repository. Supports submodule
        resolution — if the target path falls within a git submodule, the file
        is committed to the submodule's repository. Authentication is handled
        via the x-api-key header or Authorization Bearer token.
      requestBody:
        description: JSON body containing file URLs and target path
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadSandboxFilesRequest'
      responses:
        '200':
          description: Files uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSandboxFilesResponse'
        '400':
          description: Bad request - missing files or invalid path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
        '403':
          description: Forbidden - account does not have access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
        '404':
          description: Not found - no snapshot or no github_repo configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
components:
  schemas:
    UploadSandboxFilesRequest:
      type: object
      required:
        - files
      properties:
        path:
          type: string
          description: >-
            The target directory path within the repository to upload files to.
            Defaults to the repository root if omitted.
          example: assets/images
        files:
          type: array
          items:
            type: object
            required:
              - url
              - name
            properties:
              url:
                type: string
                format: uri
                description: The URL of the file to upload
                example: https://example.com/files/album-cover.png
              name:
                type: string
                description: The filename to use when committing to the repository
                example: album-cover.png
          description: Array of files to upload, each with a URL and target filename
        message:
          type: string
          description: Optional commit message. Defaults to 'Upload files via API'.
          example: Add new album artwork
    UploadSandboxFilesResponse:
      type: object
      required:
        - status
        - uploaded
      properties:
        status:
          type: string
          enum:
            - success
          description: Status of the operation
        uploaded:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: The full path of the uploaded file in the repository
              sha:
                type: string
                description: The git SHA of the created/updated file
          description: Array of uploaded file details
    SandboxErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Failed to create sandbox

````