API REFERENCE

Get File Contents

On this page

GET/api/sandboxes/file

Retrieve the contents of a file from the authenticated account's sandbox GitHub repository. Resolves the github_repo from the account's snapshot, then fetches the file at the specified path from the repository's main branch. Text files are returned verbatim. Binary files (.mp3, .png, .jpg, .mp4, .pdf, etc.) are returned base64-encoded — decode before writing to disk. 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 GET \
  --url 'https://api.recoupable.dev/api/sandboxes/file?path=src%2Findex.ts' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

pathstringrequired

The file path within the repository (e.g. "src/index.ts" or "README.md").

Responses

200File contents retrieved successfully

application/json

statusstring · enumrequired

Status of the operation

Values: "success"

contentstringrequired

The file content. Text files (.md, .json, .txt, source code, etc.) are returned verbatim. Binary files (.mp3, .png, .jpg, .mp4, .pdf, etc.) are returned base64-encoded — decode before writing to disk. The encoding is inferred from the file extension server-side; encoding field is not yet returned but planned.

400Bad request - missing or invalid path parameter

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, no github_repo, or file not found in repository

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": "Retrieve the contents of a file from the authenticated account's sandbox GitHub repository. Resolves the github_repo from the [account's snapshot](/api-reference/sandboxes/list), then fetches the file at the specified path from the repository's main branch. **Text files are returned verbatim. Binary files (`.mp3`, `.png`, `.jpg`, `.mp4`, `.pdf`, etc.) are returned base64-encoded — decode before writing to disk.** Authentication is handled via the x-api-key header or Authorization Bearer token.",
  "parameters": [
    {
      "name": "path",
      "in": "query",
      "required": true,
      "description": "The file path within the repository (e.g. \"src/index.ts\" or \"README.md\").",
      "schema": {
        "type": "string",
        "example": "src/index.ts"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "File contents retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxFileResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing or invalid path parameter",
      "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, no github_repo, or file not found in repository",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    }
  }
}