---
title: "Cool Computers HTTP API"
description: "Use the Cool Computers HTTP API and its live OpenAPI 3.1 contract."
canonical: "https://www.cool.computer/docs/api-reference/overview"
last_updated: "2026-11-20"
---
# Cool Computers HTTP API

> Use the Cool Computers HTTP API and its live OpenAPI 3.1 contract.

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](/docs/agents/cli) and [CLI guide](/docs/use/cli). |
| MCP               | Reads and owner-requested changes from an MCP client, including publishing, writing files, and running commands. | [Connect your agent](/docs/agents/overview).                        |
| 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](/openapi.json). The Python and JavaScript examples below use only built-in libraries.

For an agent's first account and computer, follow the [agent runbook](/agents.md). Agents arriving through an HTTP authentication challenge should follow the [WorkOS registration guide](/auth.md).

## Base URL

```text
https://api.cool.computer
```

Send credentials in the `Authorization` header:

```text
Authorization: Bearer <credential>
```

## Contract

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

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

The endpoint reference in this guide is written from that contract each time the site is built. The contract at that URL is the authority for the API you are calling.

## 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](/auth.md), 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](/docs/api-reference/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

```sh
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:

```python
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:

```javascript
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](/docs/api-reference/errors) before adding retry behavior.
