---

name: CoolerControl API description: Use this skill when the user asks about CoolerControl, fan curves, fan management, cooling profiles, or controlling fans on their system. Provides complete API reference for the CoolerControl daemon. version: 0.1.0

CoolerControl API Reference

CoolerControl manages fan curves and cooling devices via a REST API served by the coolercontrold daemon.

Connection

• Base URL: http://127.0.0.1:11987
• Authentication: HTTP Basic Auth
  • Username: CCAdmin
  • Default password: coolAdmin
• Login: POST /login with Authorization: Basic <base64(CCAdmin:coolAdmin)> header
  • Returns a session cookie — use -c and -b with curl cookie jar
• All mutating endpoints require authentication (GET endpoints are public)

Authentication Pattern

Always authenticate before making changes:

# Create cookie jar and login
AUTH=$(echo -n "CCAdmin:coolAdmin" | base64)
COOKIES=/tmp/cc-cookies.txt
curl -s -c $COOKIES -X POST http://127.0.0.1:11987/login -H "Authorization: Basic $AUTH"

# Use cookie jar for subsequent requests
curl -s -b $COOKIES -X POST http://127.0.0.1:11987/profiles ...

Core Endpoints

Device Discovery

GET /devices — List all devices with channels and temp sensors

Response structure:

{
  "devices": [
    {
      "name": "NVIDIA GeForce RTX 5060",
      "type": "GPU",
      "type_index": 1,
      "uid": "7796e4ec...",
      "info": {
        "channels": {
          "fan1": {
            "label": "fan1",
            "speed_options": { "min_duty": 0, "max_duty": 100, "fixed_enabled": true }
          }
        },
        "temps": {
          "GPU Temp": { "label": "GPU Temp", "number": 1 }
        },
        "profile_max_length": 17,
        "profile_min_length": 2,
        "temp_min": 0,
        "temp_max": 150
      }
    }
  ]
}

Key fields:

• uid: Unique device identifier (SHA256 hash), used in all device-specific endpoints
• info.channels: Fan channels with speed_options (null = not controllable, e.g. freq sensors)
• info.temps: Available temperature sensors — use temp_name in profile's temp_source
• Only channels with non-null speed_options are controllable fans

Status Monitoring

POST /status — Get current device statuses (temps, fan speeds, duties)

Request body: {} for latest snapshot, or {"all": true} for full history.

Response:

{
  "devices": [
    {
      "type": "GPU",
      "type_index": 1,
      "uid": "7796e4ec...",
      "status_history": [
        {
          "timestamp": "2026-02-04T21:15:49.040780763-05:00",
          "temps": [{ "name": "GPU Temp", "temp": 48.0 }],
          "channels": [
            { "name": "fan1", "rpm": 0, "duty": 0.0 },
            { "name": "fan2", "rpm": 0, "duty": 0.0 }
          ]
        }
      ]
    }
  ]
}

Profiles (Fan Curves)

Profiles define fan behavior — either a fixed speed or a temperature-based curve.

GET /profiles — List all profiles POST /profiles — Create a new profile (requires auth) PUT /profiles — Update an existing profile (requires auth)

Profile structure for a fan curve:

{
  "uid": "my-profile-id",
  "name": "Silent GPU",
  "p_type": "Graph",
  "speed_fixed": null,
  "speed_profile": [[55, 0], [65, 30], [75, 45], [82, 65], [88, 85], [92, 100]],
  "temp_source": {
    "device_uid": "<device-uid>",
    "temp_name": "GPU Temp"
  },
  "function_uid": "<function-uid>",
  "member_profile_uids": [],
  "mix_function_type": null
}

Key fields:

• uid: Unique profile identifier (user-defined string)
• p_type: "Graph" for curve, "Default" for default behavior, "Fixed" for fixed speed
• speed_profile: Array of [temperature_celsius, duty_percent] pairs (2-17 points)
• temp_source: Which temp sensor drives the curve — device_uid + temp_name
• function_uid: References a function that controls response behavior

For a fixed speed profile:

{
  "uid": "fixed-50",
  "name": "Fixed 50%",
  "p_type": "Fixed",
  "speed_fixed": 50,
  "speed_profile": null,
  "temp_source": null,
  "function_uid": "0"
}

Functions

Functions modify how duty values from profiles are applied (minimum duty, response delay, etc.).

GET /functions — List all functions POST /functions — Create a new function (requires auth) PUT /functions — Update an existing function (requires auth)

Function structure:

{
  "uid": "my-function",
  "name": "Silent Function",
  "f_type": "Identity",
  "duty_minimum": 1,
  "duty_maximum": 100,
  "step_size_min_decreasing": 0,
  "step_size_max_decreasing": 0,
  "response_delay": null,
  "deviance": null,
  "only_downward": null,
  "sample_window": null,
  "threshold_hopping": true
}

Key fields:

• duty_minimum: Minimum duty % (must be >= 1). When curve says 0%, CoolerControl uses device auto-mode for zero-RPM
• duty_maximum: Maximum duty %
• threshold_hopping: If true, jumps between defined curve points instead of interpolating
• response_delay: Seconds to wait before changing speed (prevents rapid cycling)
• The default function (uid "0") uses Identity with duty_minimum=1

Assigning Profiles to Fan Channels

PUT /devices/{device_uid}/settings/{channel_name}/profile — Assign a profile to a fan channel

Request body:

{ "profile_uid": "my-profile-id" }

Example:

curl -s -b $COOKIES \
  -X PUT "http://127.0.0.1:11987/devices/$GPU_UID/settings/fan1/profile" \
  -H "Content-Type: application/json" \
  -d '{"profile_uid": "gpu-silent"}'

To reset to default: assign profile_uid "0".

Device Settings

GET /settings/devices/{device_uid} — Get device settings (labels, disabled channels) PUT /settings/devices/{device_uid} — Update device settings

Structure:

{
  "uid": "<device-uid>",
  "name": "device name",
  "disable": false,
  "extensions": { "direct_access": false, "delay_millis": 0 },
  "channel_settings": {
    "fan1": { "label": "fan1", "disabled": false, "extension": null }
  }
}

Modes

Modes are named presets that save a collection of device/channel profile assignments.

GET /modes — List all modes POST /modes — Create a new mode PUT /modes — Update a mode POST /modes-active/{mode_uid} — Activate a mode POST /modes/order — Reorder modes

Mode structure:

{
  "uid": "silent-mode",
  "name": "Silent Mode",
  "device_channel_profiles": {
    "<device_uid>": {
      "<channel_name>": "<profile_uid>"
    }
  }
}

Alerts

GET /alerts — List all alerts (not from /status, separate endpoint) POST /alerts — Create alert PUT /alerts — Update alert

Daemon Settings

GET /settings — Get daemon settings PUT /settings — Update daemon settings

Settings include: apply_on_boot, startup_delay, poll_rate, liquidctl_integration, etc.

Other Endpoints

• GET /handshake — Returns {"shake": true} to verify connection
• GET /functions — List all functions
• POST /functions/order — Reorder functions
• POST /profiles/order — Reorder profiles
• PUT /devices/{uid}/settings/{channel}/manual — Set manual/fixed speed
• POST /shutdown — Shutdown daemon
• POST /logout — End session

Common Patterns

Creating a complete fan curve setup

1. Create a function (controls duty min/max and response behavior)
2. Create a profile with speed_profile curve points and temp_source
3. Assign the profile to a device fan channel

NVIDIA GPU zero-RPM

NVIDIA GPUs have a minimum manual fan speed (typically 30%). When CoolerControl tries to set 0%, it automatically switches to GPU auto-mode which enables the card's built-in zero-RPM feature. This is the correct behavior.

NCT6775/NCT6798 motherboard fans

These Super I/O chips have hardware-level auto fan curves (5 points, set via sysfs). CoolerControl overrides them with software control. The nct6775 kernel module must be loaded for fan detection. Key sysfs paths:

• /sys/class/hwmon/hwmonX/pwmN — PWM duty (0-255)
• /sys/class/hwmon/hwmonX/pwmN_enable — Control mode
• /sys/class/hwmon/hwmonX/fanN_input — Fan RPM reading

Systemd service

CoolerControl daemon runs as: coolercontrold.service

• Config file: /etc/coolercontrol/config.toml
• Modes file: /etc/coolercontrol/modes.json
• Alerts file: /etc/coolercontrol/alerts.json