🌐 REST API

CoolerControl exposes a comprehensive REST API that both the Desktop and Web UI use to communicate with the daemon. You can use the same API to build automations, integrate with other tools, or script routine tasks.

API Documentation

The full REST API documentation is available as an interactive OpenAPI specification:

OpenAPI Explorer

The OpenAPI explorer allows you to:

Browse all available endpoints and their parameters
View request/response schemas with examples
Try requests directly from your browser
Download the OpenAPI specification file, which enables generating code snippets for various programming languages

Base URL

By default, the daemon binds to the local loopback interface:

http://localhost:11987/

For remote access, see Remote Access and TCP Port and Address.

For real-time updates, the daemon supports Server-Sent Events (SSE). See the OpenAPI documentation for SSE endpoint details.

Authentication

The API supports two authentication methods. See the Security Overview for full details on session management, cookie flags, and security headers.

Session Authentication (Interactive Use)

HTTP Basic Auth establishes a session cookie for subsequent requests. This is what the Web UI and Desktop application use.

Username: CCAdmin
Password: The custom password you set in Access Protection

bash

# Login and save session cookie
curl -c cookies.txt -u CCAdmin:yourpassword http://localhost:11987/login

# Use session cookie for subsequent requests
curl -b cookies.txt http://localhost:11987/devices

Bearer Token Authentication (Plugins & Services)

Access tokens provide stateless authentication for plugins, external services (e.g., Home Assistant), and scripts. Create tokens from the Access Protection menu in the UI.

bash

curl -H "Authorization: Bearer cc_550e8400..." http://localhost:11987/status

python

import requests

headers = {"Authorization": "Bearer cc_550e8400..."}
response = requests.get("http://localhost:11987/devices", headers=headers)
print(response.json())

See Access Protection for token management details.

For a more complete example, see the cc.py CLI script in the CoolerControl repository.

Best Practices

Security

Use access tokens for integrations - Use access tokens instead of the admin password for plugins and external services
Never hardcode credentials - Use environment variables or secure credential storage
Use HTTPS - Enable SSL/TLS for remote access
Restrict access - Configure firewall rules and enable Access Protection
Rotate credentials - Set expiry dates on tokens and delete unused ones

Performance

Avoid excessive polling - Cache responses and don't poll too frequently
Request only what you need - Use specific endpoints rather than fetching all data
Implement retry logic - Handle errors gracefully with exponential backoff

Reliability

Check daemon availability - Verify the daemon is running before making requests
Validate responses - Check HTTP status codes and response structure
Handle timeouts - Set appropriate timeout values for your use case

Error Handling

The API returns standard HTTP status codes:

200 OK - Request successful
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication failed
404 Not Found - Resource not found
500 Internal Server Error - Server error

Rate Limiting

The API implements rate limiting to prevent abuse. Follow these guidelines:

Sensor readings - Poll at most once per second. For real-time updates, use Server-Sent Events (SSE) instead of polling.
Profile changes - Apply only when needed, not continuously

Server-Sent Events (SSE)

The API supports Server-Sent Events (SSE) for receiving real-time updates on sensor readings, alerts, and other events. This is more efficient than polling for applications that need live data.

See the OpenAPI documentation for SSE endpoint details and usage examples.

CLI Alternative

For shell scripting and quick terminal control, use the official CLI tool:

cctv - Official CoolerControl CLI/TUI

The CLI provides a user-friendly interface to the REST API and is ideal for:

Shell scripts and automation workflows
Cron jobs and systemd timers
Quick terminal control and monitoring
Testing and debugging

For usage examples, see Scripting and Custom Automation.

🌐 REST API ​

API Documentation ​

Base URL ​

Authentication ​

Session Authentication (Interactive Use) ​

Bearer Token Authentication (Plugins & Services) ​

Best Practices ​

Security ​

Performance ​

Reliability ​

Error Handling ​

Rate Limiting ​

Server-Sent Events (SSE) ​

CLI Alternative ​

See Also ​