Create a computer

curl --request POST \
  --url https://api.cool.computer/api/computers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "visibility": "public",
  "auto_delete_after": "<string>"
}
'

import requests

url = "https://api.cool.computer/api/computers"

payload = {
    "name": "<string>",
    "visibility": "public",
    "auto_delete_after": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', visibility: 'public', auto_delete_after: '<string>'})
};

fetch('https://api.cool.computer/api/computers', 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/computers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'visibility' => 'public',
    'auto_delete_after' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/computers"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"visibility\": \"public\",\n  \"auto_delete_after\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/computers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"visibility\": \"public\",\n  \"auto_delete_after\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cool.computer/api/computers")

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/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"visibility\": \"public\",\n  \"auto_delete_after\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
}

{
  "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>"
  ]
}

Computers

Create a computer

Creates a computer with its own VM, an always-on Ubuntu machine with sudo, and waits until it runs. Its URL serves nothing until a program does, and nothing is published to it. The response has status running. The request body is optional; omitting it assigns a random available name. Starting a program is a separate POST /api/computers//service/run request. The VM uses 1 of the account’s 20 VMs and memory from the account’s 8 GiB, which all its VMs share (one VM can use most of it while the others are idle); VM quota, compute access and host capacity apply. To publish a page or a site instead, use POST /api/publish. A definite failure to give the computer its VM rolls the new computer back. An unknown outcome keeps the resource and its Idempotency-Key binding for recovery. Send an Idempotency-Key when a network failure might cause a retry.

POST

api

computers

Create a computer

curl --request POST \
  --url https://api.cool.computer/api/computers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "visibility": "public",
  "auto_delete_after": "<string>"
}
'

import requests

url = "https://api.cool.computer/api/computers"

payload = {
    "name": "<string>",
    "visibility": "public",
    "auto_delete_after": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', visibility: 'public', auto_delete_after: '<string>'})
};

fetch('https://api.cool.computer/api/computers', 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/computers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'visibility' => 'public',
    'auto_delete_after' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/computers"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"visibility\": \"public\",\n  \"auto_delete_after\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/computers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"visibility\": \"public\",\n  \"auto_delete_after\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cool.computer/api/computers")

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/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"visibility\": \"public\",\n  \"auto_delete_after\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
}

{
  "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

Authorization

string

header

required

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

Idempotency-Key

string

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 - 128

Pattern: ^[!-~]+$

Example:

"req_01J6M6Y9TF9Q9QF6M1ZP8K4R2A"

Body

application/json

name

string

Optional stable name, such as agent-atlas. A name that breaks the pattern answers 400 invalid_slug with the nearest valid name as a suggestion; a name the service holds answers 400 reserved_slug.

Maximum string length: 63

Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

visibility

enum<string>

default:public

Available options:

private,

public

auto_delete_after

string

Positive Go duration such as 24h.

network_policy

object

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.

Show child attributes

Response

The computer, running on its own VM.

string

required

hostname

string

required

name

string

required

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.

visibility

enum<string>

required

Available options:

private,

public

access

enum<string>

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.

Available options:

owner,

can_use,

claim_key

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.

Show child attributes

created_at

string<date-time>

required

url

string<uri>

email_address

string<email>

auto_delete_at

string<date-time> | null

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

Start here

Connect your agent

Your computer

Use it

Build with the API

Endpoint reference

Create a computer

Authorizations

Headers

Body

Response