API REFERENCE

Upload Files

On this page

POST/api/sandboxes/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.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/sandboxes/files' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "files": [
    {
      "url": "https://example.com/files/album-cover.png",
      "name": "album-cover.png"
    }
  ]
}'

Request body required

JSON body containing file URLs and target path

application/json

pathstring

The target directory path within the repository to upload files to. Defaults to the repository root if omitted.

filesarray<object>required

Array of files to upload, each with a URL and target filename

Item properties

urlstringrequired

The URL of the file to upload

format: uri

namestringrequired

The filename to use when committing to the repository

messagestring

Optional commit message. Defaults to 'Upload files via API'.

Responses

200Files uploaded successfully

application/json

statusstring · enumrequired

Status of the operation

Values: "success"

uploadedarray<object>required

Array of uploaded file details

Item properties

pathstring

The full path of the uploaded file in the repository

shastring

The git SHA of the created/updated file

400Bad request - missing files or invalid path

application/json

errorstringrequired

Error message describing what went wrong

401Unauthorized - invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

403Forbidden - account does not have access

application/json

errorstringrequired

Error message describing what went wrong

404Not found - no snapshot or no github_repo configured

application/json

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "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"
          }
        }
      }
    }
  }
}