Cool Computers HTTP API

The HTTP API creates and operates computers from another program. It covers account inspection, computer lifecycle, command execution, files, services, visibility, outbound network policy, and computer email.

Choose an integration

Interface	Use it for	Start here
Native `cool` CLI	Shell automation, one-shot commands, publishing, and file transfer.	Install the CLI and CLI guide.
MCP	Reads and owner-requested changes from an MCP client, including publishing, writing files, and running commands.	Connect your agent.
HTTP API	Programs in any language that can send HTTPS requests.	Use the live OpenAPI contract and examples below.

Cool Computers does not publish official language SDK packages. Use your language’s HTTP client or generate a client from the OpenAPI contract. The Python and JavaScript examples below use only built-in libraries. For an agent’s first account and computer, follow the agent runbook. Agents arriving through an HTTP authentication challenge should follow the WorkOS registration guide.

Base URL

https://api.cool.computer

Send credentials in the Authorization header:

Authorization: Bearer <credential>

Contract

The live OpenAPI 3.1 contract is the source for paths, parameters, request bodies, response bodies, and error schemas:

https://www.cool.computer/openapi.json

The endpoint reference in this guide is generated from that URL. The guide does not keep a second copy of the schema.

Choose a credential

Use an access token from the email-code flow for owner-authorized setup.
Use a claimed WorkOS agent access token with cool-computers:operate for agent-authorized HTTP requests. Follow the registration guide, including human approval.
Create an API key for repeated HTTP automation with an owner access token or a claimed agent access token.
Keep browser session cookies in the browser; use bearer credentials for scripts. MCP OAuth tokens do not authorize the HTTP API.

Read API authentication before sending a request that emails a code.

First authenticated request

The examples call GET /api/auth/whoami to inspect the authenticated account without creating or changing a computer. Keep the credential in an environment variable supplied by your shell or secret manager. Do not put secrets in source code or logs.

curl

curl --fail-with-body --show-error --silent https://api.cool.computer/api/auth/whoami \
  -H "authorization: Bearer $ACCESS_TOKEN"

Python

Set COOL_API_KEY to your API key before running:

import json
import os
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

api_key = os.environ.get("COOL_API_KEY")
if not api_key:
    raise SystemExit("Set COOL_API_KEY before running this example.")

request = Request(
    "https://api.cool.computer/api/auth/whoami",
    headers={"Authorization": f"Bearer {api_key}", "Accept": "application/json"},
)
try:
    with urlopen(request, timeout=30) as response:
        print(json.dumps(json.load(response), indent=2))
except HTTPError as error:
    try:
        detail = error.read().decode("utf-8", errors="replace")
    except TimeoutError:
        raise SystemExit(f"HTTP {error.code}: response body timed out.")
    raise SystemExit(f"HTTP {error.code}: {detail}")
except URLError as error:
    raise SystemExit(f"Request failed: {error.reason}")
except TimeoutError:
    raise SystemExit("Response body timed out.")

JavaScript

Set COOL_API_KEY to your API key. Save this example as account.mjs and run node account.mjs with a current Node.js release:

const apiKey = process.env.COOL_API_KEY;
if (!apiKey) {
  throw new Error("Set COOL_API_KEY before running this example.");
}

try {
  const response = await fetch("https://api.cool.computer/api/auth/whoami", {
    headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  console.log(JSON.stringify(await response.json(), null, 2));
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

Both examples stop on an HTTP failure and report the response body, including the API’s error code and resolution when supplied. Read API errors before adding retry behavior.

Start here

Connect your agent

Your computer

Use it

Build with the API

Endpoint reference