---
title: "Upload a file tree"
description: "Extracts a tar archive beneath one destination directory on the persistent disk, creating the destination as needed."
canonical: "https://www.cool.computer/docs/api-reference/files/upload-a-file-tree"
---
# Upload a file tree

> Extracts a tar archive beneath one destination directory on the persistent disk, creating the destination as needed.

```http
PUT https://api.cool.computer/api/computers/{id}/files/upload
```

Extracts a tar archive beneath one destination directory on the persistent disk, creating the destination as needed. The archive accepts at most 10,000 entries, 64 MiB per file, and 512 MiB in aggregate. On a computer with a VM, each new entry gets the permission bits it carries, 0000 included; a directory missing for an entry inside it, the destination's included, gets 0755, and a directory that was there before the upload keeps its own mode, as with cp and scp. List each directory before the entries inside it: a directory entry other than 0755 after an entry that already made that directory is refused (400 `upload_directory_order`), and what the upload put in that directory is removed, the directory with it, so the upload in order makes it with its mode; a directory that also holds what another writer added stays, as does a file another writer replaced, and the refusal names them. On a published site with no VM, its regular files, 64 MiB in all, are published as a new release under /home/runtime/app instead, never creating a VM: each keeps only whether it is executable (0755 or 0644), directory entries and their modes are ignored, and no order is refused.

## Authorization

- A Cool Computers API key, user access token, or claimed agent access token in the Authorization header. Follow https://www.cool.computer/auth.md for agent registration and https://www.cool.computer/authentication.md for direct user credentials.

## Parameters

- `id` (path, string, at least 1 characters, required): The computer's name, such as agent-atlas, or its id (cmp_…). Every caller may use either, the computer's own runtime token included.
- `path` (query, string, at least 1 characters, required): Path inside the computer. A relative path is relative to /home/runtime, or to /home/runtime/app on a published site without a VM.

## Request body

Required.

- `application/x-tar` (string, binary)

## Responses

- `200`: The extracted file tree totals.
  - `application/json` (object)
    - `path` (string, required)
    - `files` (integer, at least 0, required)
    - `dirs` (integer, at least 0, required)
    - `bytes` (integer, int64, at least 0, required)
- `400`: Bad Request.
- `401`: Unauthorized.
- `402`: Payment Required. `pro_required`: this computer has a VM and the account is not Pro, which fences it; a site without a VM works on Free. Start Pro with cool billing upgrade, or fix a lapsed subscription with cool billing portal, or use the Account page.
- `403`: Forbidden.
- `404`: Not Found. `computer_not_found`: the computer does not exist or is not yours. `file_not_found`: the path does not exist on it.
- `409`: Conflict. `not_a_directory`: the destination or a parent is a file. `is_a_directory`: an archive entry names a file where a directory is. `outside_published_files`: the computer is a published site with no VM, which has only /home/runtime/app; name a path there. `job_taken_over`: as for POST /api/publish, after Operator took over your local agent session's comments job on the site.
- `413`: Payload Too Large.
- `429`: Too Many Requests. If the problem code is api_request_rate_exceeded, wait for Retry-After seconds; other problem codes describe a separate limit.
- `500`: Internal Server Error.
- `503`: Service Unavailable. `computer_starting` means the computer is starting, or stopped and being started again; wait for Retry-After seconds, then retry. Otherwise inspect the problem code and resolution.
- `default`: A machine-readable API error with a stable code and recovery instruction.

An error is an `application/problem+json` document with a stable `code`; [API errors](/docs/api-reference/errors) says how to handle one.

## Example

```sh
curl -X PUT "https://api.cool.computer/api/computers/$PARAM_ID/files/upload" \
  --url-query "path=$PARAM_PATH" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/x-tar" \
  --data-binary @file
```

`--url-query` encodes the value it sends and needs curl 7.87 or later.
