> ## Documentation Index > Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upload a sandbox file > Writes one file to the given absolute path inside the sandbox via `multipart/form-data`, overwriting any existing file. Authentication, host, and the error envelope are identical to the download endpoint (see `GET /files`). ## Request constraints - **The target path is given only in the `path` query parameter.** Including an additional `path` form field in the body is rejected (`400`): when the two sources disagree there is no way to know which to trust, and failing is better than guessing. - The request body must be `multipart/form-data`; any other `Content-Type` returns `415`. - One file per request. - **No chunked/resumable upload.** There is no `Range` semantics for uploads; an interrupted upload must be resent in full. A data center may enforce a per-file size limit and return `413` when exceeded; the limit is not exposed through the API. ## OpenAPI ````yaml /api-spec/sandbox_api.yaml post /files openapi: 3.0.3 info: title: GMI Sandbox API description: >- REST API for GMI Sandbox: create isolated execution environments from templates, manage their lifecycle on the control plane, and run commands or transfer files through each sandbox's own data plane. contact: name: GMI Cloud Support email: support@gmicloud.ai version: '2.0' servers: - url: https://console.gmicloud.ai/api/v2 description: Control plane security: - bearerAuth: [] tags: - name: Sandbox description: | Sandbox instance lifecycle management (Sandbox v2, /api/v2/sandboxes) - name: SandboxTemplate description: Sandbox template management (Sandbox v2, `/api/v2/templates`) - name: Sandbox-Exec description: > Sandbox execution data plane (accessed via the sandbox host and sandbox access token). These endpoints are not under the control plane's `/api/v2` path; clients connect directly to `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`. - name: Sandbox-Files description: > Sandbox file data plane (`/files`). **These endpoints are not under `/api/v2`** and do not use `Authorization: Bearer`: they are served by the sandbox's own data-plane entry point — clients connect directly to `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`. `{sandbox_key}` is the `sandbox_key` returned by the create/connect endpoints, used for data-plane host addressing. `{domain}` and `X-Access-Token` are the `domain` and `sandbox_access_token` from the same responses — no extra endpoint is needed to obtain them. This split is not historical baggage but the nature of a data plane: file transfer is long-lived, high-volume, and addressed per sandbox, differing from the control plane's short requests in both capacity model and failure domain, so they do not share an entry point. **One unified abstraction.** The same contract is served by two backend kinds (an in-sandbox file service / a data-center data-plane proxy); clients need not — and cannot — tell them apart. The cost is that the contract is their intersection: `Content-Length` on download and resumable download (`Range`/`206`) are **optional capabilities** that vary by data center, and clients must work correctly when they are absent. See the per-operation notes below. paths: /files: servers: - url: https://{sandbox_key}.{domain} description: > Sandbox data-plane entry point. Both variables come from the create/connect response: `sandbox_key` is `data.sandbox_key`, `domain` is `data.domain`. variables: sandbox_key: default: sandbox-key description: >- Sandbox key (the `sandbox_key` returned by the create/connect endpoints) domain: default: sandbox.example.com description: > The `domain` returned verbatim by the create/connect endpoints. Its default naming shape is `{idc-name}.{root-hostname}`, but clients must not assemble or derive it themselves. post: tags: - Sandbox-Files summary: Upload a sandbox file description: > Writes one file to the given absolute path inside the sandbox via `multipart/form-data`, overwriting any existing file. Authentication, host, and the error envelope are identical to the download endpoint (see `GET /files`). ## Request constraints - **The target path is given only in the `path` query parameter.** Including an additional `path` form field in the body is rejected (`400`): when the two sources disagree there is no way to know which to trust, and failing is better than guessing. - The request body must be `multipart/form-data`; any other `Content-Type` returns `415`. - One file per request. - **No chunked/resumable upload.** There is no `Range` semantics for uploads; an interrupted upload must be resent in full. A data center may enforce a per-file size limit and return `413` when exceeded; the limit is not exposed through the API. operationId: uploadSandboxFile parameters: - $ref: '#/components/parameters/SandboxFilePathQueryParam' - $ref: '#/components/parameters/SandboxFileUsernameQueryParam' requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file content. encoding: file: contentType: application/octet-stream responses: '200': description: > Write complete. The array shape exists for compatibility with existing SDKs; it currently always holds a single element. content: application/json: schema: type: array items: $ref: '#/components/schemas/SandboxFileEntry' example: - path: /home/user/data.bin name: data.bin type: file '400': $ref: '#/components/responses/SandboxFileBadRequest' '401': $ref: '#/components/responses/SandboxFileUnauthorized' '403': $ref: '#/components/responses/SandboxFileForbidden' '404': $ref: '#/components/responses/SandboxFileNotFound' '413': description: The file exceeds the data center's per-file size limit. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' '415': description: The request body is not `multipart/form-data`. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' '429': $ref: '#/components/responses/SandboxFileRateLimited' '500': $ref: '#/components/responses/SandboxFileInternalError' '502': $ref: '#/components/responses/SandboxFileUpstreamError' '507': description: The sandbox is out of disk space. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' security: - sandboxAccessToken: [] components: parameters: SandboxFilePathQueryParam: name: path in: query required: true description: > **Absolute path** inside the sandbox. Must start with `/`; relative segments such as `.` / `..` are rejected. No semantic interpretation is applied beyond existence checks; for writes, the parent directory must already exist. schema: type: string minLength: 1 example: /home/user/data.bin SandboxFileUsernameQueryParam: name: username in: query required: false description: > Perform the file operation as this user; defaults to the sandbox's default user. **Optional capability**: some data centers ignore this parameter and always act as the default user, so do not rely on it for permission isolation. schema: type: string example: user schemas: SandboxFileEntry: type: object description: Result entry for a single write. required: - path - name - type properties: path: type: string description: Absolute path of the file inside the sandbox example: /home/user/data.bin name: type: string description: File name (the last segment of `path`) example: data.bin type: type: string enum: - file description: Entry type. Only files are written today, so this is always `file`. SandboxFileError: type: object description: > Data-plane error body. **It has only `message`** — no `code`, and no platform `{request_id, data}` envelope. This differs from every endpoint under `/api/v2`. The reason is that the data plane and the control plane are separate entry points: requests do not pass through the platform gateway, so there is no platform `request_id` and no context for producing platform business error codes. Branch on the HTTP status code; `message` is for humans only — its wording is not a contract and must not be used in program logic. `message` is always the server's own wording: raw backend error text may contain internal details such as absolute paths inside the sandbox, so it is logged only and never returned. required: - message properties: message: type: string description: Human-readable error text. Not stable; do not parse. example: unauthorized responses: SandboxFileBadRequest: description: > Invalid request: `path` is missing, is not an absolute path, or the upload body carries a duplicate `path` field. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' SandboxFileUnauthorized: description: > `X-Access-Token` is missing, malformed, expired, or does not belong to this sandbox. **All of these cases return exactly the same status code and message**, so they cannot be told apart. This is deliberate: distinguishable errors would let callers use this endpoint as a sandbox-existence probe. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' SandboxFileForbidden: description: >- The token is valid, but file permissions inside the sandbox do not allow the operation. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' SandboxFileNotFound: description: > The target file or its parent directory does not exist, or the sandbox is no longer available (deleted/stopped). These cases are likewise not distinguished. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' SandboxFileRateLimited: description: Data-plane rate limit hit; back off and retry. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' SandboxFileInternalError: description: Data-plane internal error. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' SandboxFileUpstreamError: description: > The data plane's own backend call failed. **This is a server-side problem, not a caller credential problem** — re-fetching the token will not help; back off and retry, or report it. content: application/json: schema: $ref: '#/components/schemas/SandboxFileError' securitySchemes: bearerAuth: type: http scheme: bearer description: > API Key or Access Token, always sent as `Authorization: Bearer `. The gateway recognizes the token type automatically. sandboxAccessToken: type: apiKey in: header name: X-Access-Token description: > Sandbox data-plane token — the `sandbox_access_token` returned by the create/connect endpoints. Used for `/files`, Sandbox-Exec, and other data-plane endpoints; the control plane (`/api/v2`) does not accept it, and conversely the control plane's `Authorization: Bearer` is invalid on the data plane. The token is bound to its sandbox: using sandbox A's token against sandbox B's host fails. It stays valid until the sandbox's lifetime ends; there is no separate rotation endpoint (`rotate_traffic_token` rotates the port traffic token `traffic_access_token` and does not affect this one). ````