---
title: "Create a release"
description: "Records a release manifest: every file's path, sha256 and size, and optionally whether it is executable."
canonical: "https://www.cool.computer/docs/api-reference/publishing/create-a-release"
---
# Create a release

> Records a release manifest: every file's path, sha256 and size, and optionally whether it is executable.

```http
POST https://api.cool.computer/api/computers/{id}/releases
```

Records a release manifest: every file's path, sha256 and size, and optionally whether it is executable. The response lists the content hashes the server does not hold yet (content is deduplicated per computer by sha256) and the next request to make. Paths are relative; .., absolute paths, backslashes, NUL, duplicates and anything under .git/ are rejected. Hidden paths (a segment starting with ., except .well-known) and node_modules may be in a release but are never served. 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. No file's path may be the folder of another file's. Only a computer without a VM takes releases.

## 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.

## Request body

Required.

- `application/json` (object)
  - `files` (array of object, 1 to 20000 items, required)
    - `path` (string, at least 1 characters, required): Relative path such as index.html or assets/app.js.
    - `sha256` (string, pattern `^[0-9a-f]{64}$`, required)
    - `size` (integer, int64, 0 to 26214400, required)
    - `executable` (boolean, default false): A computer's VM gets this file with mode 0755 instead of 0644, so run or a service can start it. Serving files from the edge ignores it.

## Responses

- `201`: The new release, the hashes to upload and the next request.
  - `application/json` (object)
    - `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)
    - `missing` (array of string, required)
    - `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.
- `400`: Bad Request. `invalid_release` names the rejected path or limit.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not Found. `computer_not_found`: the computer does not exist or is not yours.
- `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`: the computer is gaining a VM.
- `413`: Payload Too Large.
- `422`: Unprocessable Content. `content_size_conflict`: one sha256 is listed with two sizes.
- `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. `artifacts_unavailable` means publishing is not configured on this server.
- `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/computers/$PARAM_ID/releases" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  --data '{"files":[{"path":"index.html","sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","size":0}]}'
```
