Publish files in one request
curl --request POST \
--url https://api.cool.computer/api/publish \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-tar' \
--data '<string>'import requests
url = "https://api.cool.computer/api/publish"
payload = "<string>"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/x-tar"
}
response = requests.post(url, data=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/x-tar'},
body: '<string>'
};
fetch('https://api.cool.computer/api/publish', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cool.computer/api/publish",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "<string>",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/x-tar"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cool.computer/api/publish"
payload := strings.NewReader("<string>")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/x-tar")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cool.computer/api/publish")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/x-tar")
.body("<string>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cool.computer/api/publish")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/x-tar'
request.body = "<string>"
response = http.request(request)
puts response.read_body{
"computer": {
"id": "<string>",
"hostname": "<string>",
"name": "<string>",
"ip": "<string>",
"status": "<string>",
"visibility": "private",
"access": "owner",
"copy_enabled": true,
"site": true,
"network_policy": {
"mode": "open",
"allowed_hosts": [
"api.example.com"
]
},
"created_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"email_address": "jsmith@example.com",
"auto_delete_at": "2023-11-07T05:31:56Z",
"creation_mode": "<string>"
},
"release": {
"number": 2,
"state": "uploading",
"live": true,
"files": 1,
"bytes": 1,
"created_at": "2023-11-07T05:31:56Z",
"ready_at": "2023-11-07T05:31:56Z"
},
"url": "<string>",
"vm": true,
"next": {
"action": "upload",
"upload": {
"method": "PUT",
"href": "<string>"
},
"finalize": {
"method": "PUT",
"href": "<string>"
}
},
"release_url": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}Publishing
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. 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; 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; remove archive comments or send tar or tar.gz if it exceeds this limit. 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 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).
POST
/
api
/
publish
Publish files in one request
curl --request POST \
--url https://api.cool.computer/api/publish \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-tar' \
--data '<string>'import requests
url = "https://api.cool.computer/api/publish"
payload = "<string>"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/x-tar"
}
response = requests.post(url, data=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/x-tar'},
body: '<string>'
};
fetch('https://api.cool.computer/api/publish', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cool.computer/api/publish",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "<string>",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/x-tar"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cool.computer/api/publish"
payload := strings.NewReader("<string>")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/x-tar")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cool.computer/api/publish")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/x-tar")
.body("<string>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cool.computer/api/publish")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/x-tar'
request.body = "<string>"
response = http.request(request)
puts response.read_body{
"computer": {
"id": "<string>",
"hostname": "<string>",
"name": "<string>",
"ip": "<string>",
"status": "<string>",
"visibility": "private",
"access": "owner",
"copy_enabled": true,
"site": true,
"network_policy": {
"mode": "open",
"allowed_hosts": [
"api.example.com"
]
},
"created_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"email_address": "jsmith@example.com",
"auto_delete_at": "2023-11-07T05:31:56Z",
"creation_mode": "<string>"
},
"release": {
"number": 2,
"state": "uploading",
"live": true,
"files": 1,
"bytes": 1,
"created_at": "2023-11-07T05:31:56Z",
"ready_at": "2023-11-07T05:31:56Z"
},
"url": "<string>",
"vm": true,
"next": {
"action": "upload",
"upload": {
"method": "PUT",
"href": "<string>"
},
"finalize": {
"method": "PUT",
"href": "<string>"
}
},
"release_url": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 499,
"code": "<string>",
"detail": "<string>",
"resolution": "<string>",
"context": {},
"suggestions": [
"<string>"
]
}Authorizations
bearerAuthclaimKeyAuth
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.
Headers
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.
Required string length:
1 - 128Pattern:
^[!-~]+$Example:
"req_01J6M6Y9TF9Q9QF6M1ZP8K4R2A"
Query Parameters
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-- in one DNS label; slug_too_long_for_releases otherwise. A computer name, its address .cool.computer: lowercase letters and digits in words joined by single hyphens. The service names in not.enum are reserved.
Maximum string length:
63Pattern:
^[a-z0-9]+(?:-[a-z0-9]+)*$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).
Available options:
public, private Body
application/x-tarapplication/gzipapplication/ziptext/html
The body is of type file.
Response
The computer and the receipt of its new live release. A publish without an account answers AnonymousPublishResult.
- Option 1
- Option 2