---
title: "Publish files in one request"
description: "Publishes a whole release in one body: a tar, gzip-compressed tar or zip archive, or one HTML page served as index.html."
canonical: "https://www.cool.computer/docs/api-reference/publishing/publish-files-in-one-request"
---
# Publish files in one request

> Publishes a whole release in one body: a tar, gzip-compressed tar or zip archive, or one HTML page served as index.html.

```http
POST https://api.cool.computer/api/publish
```

Publishes a whole release in one body: a tar, gzip-compressed tar or zip archive, or one HTML page served as index.html. Archives may hold only regular files and directories; an entry whose mode has any execute bit is executable. Without computer, creates a computer that serves the files with no VM (a Free account holds at most 20 sites at once, 403 site_limit_reached, and a Pro account any number; an account creates or claims at most 100 such sites in any 24 hours while they remain sites, 429 artifact_creation_rate_exceeded; a site that gains its VM leaves this budget); with computer, makes them that computer's new live release, only while the computer has no VM: a computer with a VM answers 409 computer_has_vm, and its files change with the files API or exec instead. A cool.json at the release root configures serving: spa, and run with an optional port, a shortcut for starting a server by hand: the computer gets its VM, the files are written to /home/runtime/app and served from there, and run starts there as the managed service, answering every path, /api included, once it is ready, after which the folder is no longer served as files; the publish waits up to 60 seconds for the program's port to accept connections; a program still starting then is no failure, and the publish succeeds with a Cool-Notice header saying it keeps starting; a program that fails to start or ends before it is ready fails the publish with 502 server_start_failed, and the release stays live and the computer keeps its VM and the program's logs, also when the publish created it, unless its link did not move to the VM either, which deletes a created computer; or functions, the path of one bundled .js or .mjs ES module of at most 1 MiB that answers /api and every /api/... request, with secrets, the name of an account secret set whose keys it gets as env (a key delivered by proxy only once the computer has its VM, as a stand-in, its value set as Authorization by the computer's egress proxy on the https requests its rule matches); a release cannot declare both functions and run. On the site's own URL the live release's functions send email from the site's address with env.EMAIL.send({ to, subject, text or html, idempotencyKey }), as POST /api/computers/{id}/emails/send does, with its limits and billing; EMAIL is a reserved secret key. Their fetch() to cool.computer hosts, this API included, is refused with 403. A cool.json with "database": true requires functions and gives only the live release's functions a site-owned database through env.DB; DB is a reserved secret key. When the site gets its VM, its database moves to the VM and env.DB uses that local data. The body is validated, cool.json included, before anything is created, and a computer this request created is deleted again if a later step fails, except a run release's program failing once the computer has its VM and its link moved there. With an account, once the body is received the publish finishes even if the client disconnects; a publish without an account still stops when its client goes away and deletes the computer it created. Limits: 20,000 files, 25 MiB per file and 1 GiB in total, paths of at most 1,024 bytes and names of at most 255, and in an archive 8 MiB of paths in total; a release that declares run holds at most 10,000 files and 512 MiB. ZIP central-directory metadata (headers, paths, extra fields and comments, including directories) is limited to 8 MiB for all callers; when comments or extra fields take it over, remove them or send tar or tar.gz. Send an Idempotency-Key: a retry of the same request with the same key returns the original response or finishes that release, and never publishes again. Without any credential, it publishes without an account: files only (a release that declares run or functions answers 403 sign_in_required_for_servers), at most 1,000 files, 10 MiB per file and 100 MiB in total, and at most 20 such publishes per client IP per hour, 100 per IPv6 /48, and 10 unclaimed computers per client IP, 50 per IPv6 /48, at once (429 anonymous_publish_rate_exceeded or unclaimed_computer_limit). The created computer is public and is deleted 24 hours later unless someone claims it; the response adds claim_key, returned only once, claim_url, whose fragment carries the computer ID and the key, and expires_at. To publish to that computer again before then, send ?computer=\<computer ID> with Authorization: Claim \<claim_key>; that does not extend expires_at. A signed-in user claims the computer with POST /api/computers/{id}/claim. An Idempotency-Key needs an account: with no credential it is answered 401, and a Claim key's publish refuses one (400 idempotency_key_requires_account). The body must keep coming: it may wait at most a minute in all for each 4 KiB, and the request at most 15 minutes, or it is ended with 408 request_body_timeout; send it again.

## 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.
- Claim \<claim_key>: the claim key a publish without an account returned. Until the computer is claimed or expires it authorizes further publishes to that computer, claiming it, and its publisher's agent on that computer's comments: the board, pull without a job, create (with ink), reply, resolve, reopen, delete and watch, with owner rights on that one site and identity-free answers like a computer's runtime token. Any other computer, a wrong key, or a claimed computer answers 404 computer_not_found; an expired one 409 claim_unavailable. Signed in after claiming, use a bearer and drop the claim key.
- No credential: the request is also answered without one.

## Parameters

- `Idempotency-Key` (header, string, pattern `^[!-~]+$`, 1 to 128 characters): A caller-generated key for safely retrying this side effect. The server retains the key and response for 24 hours. Reusing it with the same request replays the original response, except after a failure that proves nothing happened: that is kept for one minute, and one that sets Retry-After is not kept, so a retry after it runs the request again; reusing it with different input returns 409.
- `computer` (query, string, at least 1 characters): Existing computer ID or name to publish to. Omit it to create a computer. Without an account, only the unclaimed computer the Claim key belongs to.
- `name` (query, string, pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`, at most 63 characters, not "abuse", "admin", "admin-api", "api", "edge-api", "hostmaster", "mail", "mailer-daemon", "no-reply", "noreply", "postmaster", "root", "security", "signup", "support", "webmaster", "www"): Name for a created computer, such as agent-atlas. Unless the release declares run, it is at most 56 characters, leaving room for release hostnames up to r9999--\<name> in one DNS label; slug_too_long_for_releases otherwise.
- `visibility` (query, "public" or "private"): Visibility of a created computer: private serves it only to the account and the people it is shared with; public is the default. Only without computer (visibility_on_existing_computer otherwise), and only with an account (sign_in_required_for_private otherwise).

## Request body

Required.

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

- `application/gzip` (string, binary)

- `application/zip` (string, binary)

- `text/html` (string)

## Responses

- `201`: The computer and the receipt of its new live release. A publish without an account answers AnonymousPublishResult.
  - `application/json` (PublishResult or AnonymousPublishResult)
    - PublishResult
      - `computer` (object, required)
        - `id` (string, required)
        - `hostname` (string, required)
        - `name` (string, required)
        - `ip` (string, required)
        - `status` (string, required): artifact (no VM), creating, running, stopped while its account's Pro has lapsed (its VM is stopped and deleted at auto_delete_at unless Pro returns; once Pro returns it can show running briefly until the reconciler has started its VM), or deleting from when its deletion begins until it is gone.
        - `url` (string, uri)
        - `email_address` (string, email)
        - `visibility` ("private" or "public", required)
        - `access` ("owner" or "can_use" or "claim_key", required): What the caller holds: owner, can_use for a computer shared with them, or claim_key in the response to a publish without an account, whose claim key republishes to the computer and claims it.
        - `copy_enabled` (boolean, required): People other than the owner may copy the computer into their own accounts (PUT /api/computers/{id}/copy-settings).
        - `site` (boolean, required): The URL serves the computer's published files: from the edge, or from its VM's built-in site server until a port is first exposed, when the program on it takes every path but the functions' for good.
        - `network_policy` (object, required): Outbound access policy. open allows public destinations, none blocks outbound access, and allowlist permits only the named public hosts. Private and reserved addresses remain blocked.
          - `mode` ("open" or "none" or "allowlist", required)
          - `allowed_hosts` (array of string, at most 100 items): Required and non-empty only when mode is allowlist. Each value is a hostname, public IP, or leading wildcard such as \*.example.com, without a scheme, port, path, or CIDR.
        - `created_at` (string, date-time, required)
        - `auto_delete_at` (string or null, date-time): When the computer is deleted by itself: its own auto-delete deadline, or, for a VM of an account whose Pro lapsed, when its stopped VMs are deleted, whichever comes first.
        - `creation_mode` (string)
      - `release` (object, required)
        - `number` (integer, at least 1, required)
        - `state` ("uploading" or "ready" or "failed", required)
        - `live` (boolean, required)
        - `files` (integer, at least 0, required)
        - `bytes` (integer, int64, at least 0, required)
        - `created_at` (string, date-time, required)
        - `ready_at` (string, date-time)
      - `url` (string, uri, required): The computer's URL, which serves the live release.
      - `release_url` (string, uri): This release's own hostname r\<n>--\<name>. Absent once the computer's VM serves its URL.
      - `vm` (boolean, required): Whether the computer's VM serves its URL, because a server on it answered.
      - `next` (object, required): What to do next: upload the missing hashes, finalize, or nothing (done).
        - `action` ("upload" or "finalize" or "done", required)
        - `upload` (object)
          - `method` ("PUT" or "POST", required)
          - `href` (string, required): API path; {sha256} stands for each missing hash.
        - `finalize` (object)
          - `method` ("PUT" or "POST", required)
          - `href` (string, required): API path; {sha256} stands for each missing hash.
    - AnonymousPublishResult
      - `computer` (object, required)
        - `id` (string, required)
        - `hostname` (string, required)
        - `name` (string, required)
        - `ip` (string, required)
        - `status` (string, required): artifact (no VM), creating, running, stopped while its account's Pro has lapsed (its VM is stopped and deleted at auto_delete_at unless Pro returns; once Pro returns it can show running briefly until the reconciler has started its VM), or deleting from when its deletion begins until it is gone.
        - `url` (string, uri)
        - `email_address` (string, email)
        - `visibility` ("private" or "public", required)
        - `access` ("owner" or "can_use" or "claim_key", required): What the caller holds: owner, can_use for a computer shared with them, or claim_key in the response to a publish without an account, whose claim key republishes to the computer and claims it.
        - `copy_enabled` (boolean, required): People other than the owner may copy the computer into their own accounts (PUT /api/computers/{id}/copy-settings).
        - `site` (boolean, required): The URL serves the computer's published files: from the edge, or from its VM's built-in site server until a port is first exposed, when the program on it takes every path but the functions' for good.
        - `network_policy` (object, required): Outbound access policy. open allows public destinations, none blocks outbound access, and allowlist permits only the named public hosts. Private and reserved addresses remain blocked.
          - `mode` ("open" or "none" or "allowlist", required)
          - `allowed_hosts` (array of string, at most 100 items): Required and non-empty only when mode is allowlist. Each value is a hostname, public IP, or leading wildcard such as \*.example.com, without a scheme, port, path, or CIDR.
        - `created_at` (string, date-time, required)
        - `auto_delete_at` (string or null, date-time): When the computer is deleted by itself: its own auto-delete deadline, or, for a VM of an account whose Pro lapsed, when its stopped VMs are deleted, whichever comes first.
        - `creation_mode` (string)
      - `release` (object, required)
        - `number` (integer, at least 1, required)
        - `state` ("uploading" or "ready" or "failed", required)
        - `live` (boolean, required)
        - `files` (integer, at least 0, required)
        - `bytes` (integer, int64, at least 0, required)
        - `created_at` (string, date-time, required)
        - `ready_at` (string, date-time)
      - `url` (string, uri, required): The computer's URL, which serves the live release.
      - `release_url` (string, uri): This release's own hostname r\<n>--\<name>.
      - `vm` (boolean, required): Always false: a publish without an account serves files only.
      - `next` (object, required): What to do next: upload the missing hashes, finalize, or nothing (done).
        - `action` ("upload" or "finalize" or "done", required)
        - `upload` (object)
          - `method` ("PUT" or "POST", required)
          - `href` (string, required): API path; {sha256} stands for each missing hash.
        - `finalize` (object)
          - `method` ("PUT" or "POST", required)
          - `href` (string, required): API path; {sha256} stands for each missing hash.
      - `claim_key` (string): Authorizes publishing to this computer again (Authorization: Claim \<claim_key>) and claiming it. Returned only by the publish that created the computer, and never again.
      - `claim_url` (string, uri): https://www.\<domain>/claim#\<computer ID>.\<claim_key>, for a signed-in user to claim the computer. Returned with claim_key.
      - `comment_url` (string, uri): https://www.\<domain>/comment#\<computer ID>.\<comment key>, for the user only: the browser that opens it comments on the site without signing in, and reaches the agent that watches it with the claim key, until the site is claimed or expires. Returned with claim_key, and never again.
      - `expires_at` (string, date-time, required): When the computer is deleted unless someone claims it: 24 hours after it was created. Publishing again does not extend it.
- `400`: Bad Request. `invalid_release` names the rejected path, limit or cool.json field. `idempotency_key_requires_account`: a claim key's publish takes no Idempotency-Key. `invalid_request`: a Claim key needs ?computer=. `visibility_on_existing_computer`: an existing computer keeps its visibility.
- `401`: Unauthorized. ?computer= without an account credential needs Authorization: Claim \<claim_key>.
- `402`: Payment Required. `pro_required`: a release that declares run needs a VM, and VMs need Pro; start Pro with cool billing upgrade, or fix a lapsed subscription with cool billing portal, or use the Account page.
- `403`: Forbidden. `sign_in_required_for_servers`: a publish without an account cannot declare run or functions, because both run code. `sign_in_required_for_private`: a computer published without an account is public. `site_limit_reached`: a Free account holds at most 20 sites; delete one or upgrade to Pro.
- `404`: Not Found. The computer does not exist or is not owned by this account, or the claim key is not this unclaimed computer's.
- `409`: Conflict. `computer_has_vm`: the computer has a VM, so publishing cannot change it; change its files with the files API or exec, or publish to a new name. `publish_in_progress`: another publish of the computer is running. `name_taken`: another account holds the name (names are shared by everyone on Cool Computers); send one of the free names in suggestions instead. `name_is_yours`: one of your computers already has the name; context has vm and the visibility it keeps. Publish a new release to a site with ?computer=\<name>, write a computer with a VM's files with the files API, change its visibility first if needed, or choose another name for a new computer. `name_releasing`: one of your own computers holds the name while it is still being created or deleted; wait for Retry-After seconds, then retry. `idempotency_in_progress`: wait for Retry-After seconds, then retry the identical request with the same key. `idempotency_key_conflict`: the key was used for a different request. `claim_unavailable`: the unclaimed computer expired. `job_taken_over`: Operator took over your session's comments job on the site after it went quiet; stop and run cool comments watch again.
- `413`: Payload Too Large. `release_too_large`.
- `415`: Unsupported Media Type. `unsupported_publish_body`: send application/x-tar, application/gzip, application/zip or text/html.
- `422`: Unprocessable Content. `release_has_no_files`: no file of a release without run is served (hidden files and node_modules never are). `slug_too_long_for_releases`, `content_size_conflict`, `functions_and_run`: cool.json declares both, `secret_set_not_found`: cool.json secrets names a set the account does not have, or `secret_set_too_large`: functions on the edge get at most 64 env keys of at most 5,000 bytes.
- `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. computer_quota_exceeded means the account's VM quota is full. artifact_creation_rate_exceeded means the account has 100 counted site admissions in the last 24 hours; a site gaining its VM removes an admission; context.retry_at and Retry-After say when the oldest counted admission expires if no site gains its VM first, and publishing to a site it already has is not limited. Without an account, anonymous_publish_rate_exceeded means this client IP published 20 times in the last hour, or its IPv6 /48 100 times, and unclaimed_computer_limit that it holds 10 unclaimed computers, or its IPv6 /48 holds 50.
- `500`: Internal Server Error.
- `502`: Bad Gateway. `artifact_deploy_failed`: publish the same files again, unless its resolution says the link to the computer's VM did not move; then do what that resolution says. `linux_create_failed`: giving the computer its VM failed and it stays a published site; `server_start_failed`: after the computer got its VM with the release's files, its program failed to start or ended before its port accepted connections; `context.step` names the failing step. The release is live and the computer keeps its VM, so read why with GET /api/computers/{id}/service/logs, fix the program there with the files API or exec and start it on the port the resolution names. If its link did not move to the VM either, a publish that created the computer deletes it again, as the resolution says; an existing computer keeps its VM, and POST /api/computers/{id}/vm finishes moving its link.
- `503`: Service Unavailable. `artifacts_unavailable` means publishing is not configured on this server; `host_capacity_full` or `host_capacity_unavailable` means a release that declares run cannot get a VM now.
- `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 POST "https://api.cool.computer/api/publish" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/x-tar" \
  --data-binary @file
```
