# Upload Files

Source: https://recoupable.dev/docs/api-reference/sandboxes/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.

## POST /api/sandboxes/files

Full OpenAPI specification: https://recoupable.dev/docs/spec/content.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "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"
    }
  ],
  "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"
          }
        }
      }
    }
  }
}
```