> ## Documentation Index > Fetch the complete documentation index at: https://docs.incredibuild.com/llms.txt > Use this file to discover all available pages before exploring further. # Build Cache API Last updated on Dec 31, 2025 This feature is only available in Incredibuild's [Enterprise Plan](/windows/10.35.0/pricing-plans). The Build Cache API enables API users to automatically carry out Build Cache actions with most of the capabilities of those done by the Build Cache Manager UI, including cluster and node actions such as start, stop, restart, clear cache, and log level adjustments. This API functions only if the user has an active API key feature on their license; rate limiting is aligned to the license API. The API endpoints support batch operations on multiple nodes and include mechanisms for retrieving cluster and node lists. These include Cluster level and specific Node actions. In addition, requests can be sent to multiple nodes simultaneously. Use of this API requires an [API Key](/windows/10.35.0/api-keys) and an Enterprise license. ## API Key and Syntax Every API call must include a header with a valid key called client-api-key and the value of your [API key](/windows/10.35.0/api-keys). All APIs are case sensitive. **Request Endpoint** ``` POST https://{IB Coordinator IP Address/Hostname}:{Coordinator UI Port}/api/buildcache/{clusters/nodes}/{cluster/nodeName}/{action}?coordinatorId={coordID}&version=1.5.0 ``` Where: 1. **IB Coordinator IP Address/Hostname** - The IP address or hostname of the Coordinator. 2. **Coordinator UI Port** - The port number defined during installation. By default, this is 8000. 3. **clusters/nodes** - Determines whether the action is on an entire cluster or is on a specific node. 4. **cluser/nodeName** - The cluster or node name being queried / acted upon. 5. **action** - stop, start, restart, clear 1. stop service 2. start service 3. restart service 4. clear cache 5. LogLevel (Cluster only) 6. **Coordinator ID** - The ID assigned by Incredibuild to your Coordinator. You can view this in the **Coordinator Manager > Settings > API Access** area.\\ 7. **Version** - The version of the API. Currently only version 1.5.0 is supported. If you do not specify a version in the API call, the lowest supported version is used. **Header** Every API call must include a header with a key called **client-api-key** and its value (case sensitive). ## Support Matrix | Build Cache API Version | Required version of Incredibuild for Windows | | ----------------------- | -------------------------------------------- | | 1.5.0 | 10.31 | ## **Request Format** The request URL can contain any of the following fields. | Request Parameter | Values | Type | Appearance in UI | | ----------------- | -------------------------------------------------------- | ------ | ------------------------- | | clusterName | Any | String | Build Cache Cluster Name | | nodeName | Any | String | Build Cache Node Hostname | | action | stop \| start \| restart \| clear | String | The action to perform | | logLevel | Minimal \| Basic \| Intermediate \| Extended \| Detailed | String | Log Level | ## POST Actions on Nodes ### **HTTP Method - PO** **Example Request:** Stop ``` POST https://{coordIP}:8000/api/buildcache/nodes/{nodeName}/stop?coordinatorId={coordID}&version=1.5.0 ``` **Example Response** [Copy](javascript:void\(0\);) ``` { "id": "AW9222_H_1_0", "success": true } ``` **Example Request:** \{start/restart/clear} ``` POST https://{coordIP}:8000/api/buildcache/nodes/{nodeName}/{action}?coordinatorId={coordID}&version=1.5.0 ``` **Example Response:** [Copy](javascript:void\(0\);) ``` { "id": "AW9222_H_1_0", "success": true } ``` **Example Request:** Clear cache on multiple nodes ``` POST https://{coordIP}:8000/api/buildcache/nodes/clear?coordinatorId={coordID}&version=1.5.0 ``` Example Syntax: [Copy](javascript:void\(0\);) ``` { "nodes": [ "node_0", "node_1" ] } ``` ```json theme={null} { "level": "Detailed" } ``` Example Body: [Copy](javascript:void\(0\);) ``` { "nodes": [ "AW9222_H_1_0", "AW9222_H_1_1" ] } ``` Example Response: [Copy](javascript:void\(0\);) ``` { "results": [ { "id": "AW9222_H_1_0", "success": true }, { "id": "AW9222_H_1_1", "success": true } ], "overallSuccess": true } ``` **Example Request:** Stop service on an empty node list ``` POST https://{coordIP}:8000/api/buildcache/clusters/InvalidClusterName/stop?coordinatorId={coordID}&version=1.5.0 ``` [Copy](javascript:void\(0\);) ``` { "statusCode": 400, "timestamp": "2025-11-19T09:20:59.628Z", "path": "/api/buildcache/nodes/clear?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "Agent not found" } ``` **Example Request:** Stop an invalid node ``` POST https://{coordIP}:8000/api/buildcache/nodes/InvalidNode/stop?coordinatorId={coordID}&version=1.5.0 ``` Example Response: [Copy](javascript:void\(0\);) ``` { "statusCode": 404, "timestamp": "2025-11-19T09:20:24.705Z", "path": "/api/buildcache/nodes/InvalidNode/clear?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "Agent not found", "ibErrorCode": 9512 } ``` ## POST Actions on Clusters ### **HTTP Method - POST** **Example Request:** Stop service on a cluster ``` POST https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/stop?coordinatorId={coordID}&version=1.5.0 ``` Example Response: [Copy](javascript:void\(0\);) ``` { "id": "ClusterA", "success": true } ``` **Example Request:** \{start or restart} service on a cluster, or clear its file cache. The action here is any of (start/restart/clear). ``` POST https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/{action}?coordinatorId={coordID}&version=1.5.0 ``` Example Response: [Copy](javascript:void\(0\);) ``` { "id": "ClusterA", "success": true } ``` **Example Request**: Invalid Action ``` POST https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/AnyInvalidAction?coordinatorId={coordID}&version=1.5.0 ``` Example Response: [Copy](javascript:void\(0\);) ``` { "statusCode": 400, "timestamp": "2025-11-19T08:23:25.074Z", "path": "/api/buildcache/nodes/InvalidNode/clear?,coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "Invalid action", "ibErrorCode": 9600 } ``` **Example Request:** Invalid cluster name ``` POST https://{coordIP}:8000/api/buildcache/clusters/InvalidClusterName/stop?coordinatorId={coordID}&version=1.5.0 ``` Example Response: [Copy](javascript:void\(0\);) ``` { "statusCode": 404, "timestamp": "2025-11-19T08:24:41.771Z", "path": "/api/buildcache/clusters/InvalidCluster/stop?,coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "Invalid parameters", "ibErrorCode": 9600 } ``` ## Data Retrieval **Example Request:** GET all Clusters ``` GET https://{coordIP}:8000/api/buildcache/clusters?coordinatorId={coordID}&version=1.5.0 ``` **Example Response** [Copy](javascript:void\(0\);) ``` [ { "name": "ClusterA", "nodes": [ { "agentId": "AW9222_H_1_0", "status": "Online" }, { "agentId": "AW9222_H_1_1", "status": "Online" }, { "agentId": "AW9222_H_1_2", "status": "Online" }, { "agentId": "AW9222L10", "status": "Online" } ] } ] ``` **Example Request:** GET all Nodes in a Cluster ``` GET https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/nodes?coordinatorId={coordID}&version=1.5.0 ``` **Response Example** [Copy](javascript:void\(0\);) ``` [ { "agentId": "AW9222_H_1_0", "status": "Online", "buildCacheData": { "port": 51100, "logLevel": "Intermediate", "cacheSizeGB": 50, "usedCacheSizeBytes": 0.00004589743912220001, "freeDiskSpaceGB": 177.06983184814453, "lastEvictionTime": null, "timestamp": "2025-11-19T09:44:16.066Z" } }, { "agentId": "AW9222_H_1_1", "status": "Online", "buildCacheData": { "port": 51100, "logLevel": "Intermediate", "cacheSizeGB": 50, "usedCacheSizeBytes": 0.00004589743912220001, "freeDiskSpaceGB": 177.00388717651367, "lastEvictionTime": null, "timestamp": "2025-11-19T09:44:15.120Z" } }, { "agentId": "AW9222_H_1_2", "status": "Online", "buildCacheData": { "port": 51100, "logLevel": "Intermediate", "cacheSizeGB": 50, "usedCacheSizeBytes": 0.00004589743912220001, "freeDiskSpaceGB": 177.0080680847168, "lastEvictionTime": null, "timestamp": "2025-11-19T09:44:14.943Z" } }, { "agentId": "AW9222L10", "status": "Online", "buildCacheData": { "port": 51100, "logLevel": "Intermediate", "cacheSizeGB": 50, "usedCacheSizeBytes": 0.00004589743912220001, "freeDiskSpaceGB": 206.85344314575195, "lastEvictionTime": null, "timestamp": "2025-11-19T09:44:15.487Z" } } ] ``` **Example Request:** GET Invalid Cluster Name ``` GET https://{coordIP}:8000/api/buildcache/clusters/InvalidCluster/nodes?coordinatorId={coordID}&version=1.5.0 ``` **Example Response** [Copy](javascript:void\(0\);) ``` { "statusCode": 404, "timestamp": "2025-11-19T09:46:33.432Z", "path": "/api/buildcache/clusters/InvalidCLuster/nodes?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "Invalid parameters", "ibErrorCode": 9600 } ``` ## Authentication & Licenses **Example Request:** GET Clusters (you have a valid API key) ``` GET https://{coordIP}:8000/api/buildcache/clusters?coordinatorId={coordID}&version=1.5.0 ``` **Response Example** [Copy](javascript:void\(0\);) ``` [ { "name": "ClusterA", "nodes": [ { "agentId": "AW9222_H_1_0", "status": "online" }, { "agentId": "AW9222_H_1_1", "status": "Online" }, { "agentId": "AW9222_H_1_2", "status": "Online" }, { "agentId": "AW9222L10", "status": "Online" } ] } ] ``` **Example Request:** GET Clusters (the required API key is not present) ``` GET https://{coordIP}:8000/api/buildcache/clusters?coordinatorId={coordID}&version=1.5.0 ``` **Response Example** [Copy](javascript:void\(0\);) ``` { "statusCode": 401, "timestamp": "2025-11-19T09:29:07.607Z", "path": "/api/buildcache/clusters?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "API key not provided", "ibErrorCode": 1002 } ``` **Example Request: GET Clusters** (you have an Invalid API key) Your license is invalid. In the Authorization section, under Auth Type, there is an API key, but it is invalid. ``` GET https://{coordIP}:8000/api/buildcache/clusters?coordinatorId={coordID}&version=1.5.0 ``` **Response Example** [Copy](javascript:void\(0\);) ``` { "statusCode": 401, "timestamp": "2025-11-19T09:29:52.652Z", "path": "/api/buildcache/clusters?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "API key provided is invalid", "ibErrorCode": 2006 } ``` **Example Request:** GET Clusters. Your license does not have the required API access feature. ``` GET https://{coordIP}:8000/api/buildcache/clusters?coordinatorId={coordID}&version=1.5.0 ``` Response Example [Copy](javascript:void\(0\);) ``` { "statusCode": 401, "timestamp": "2025-11-19T09:34:25.028Z", "path": "/api/buildcache/clusters?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "Your license does not include API access. Contact your CSM to upgrade today", "ibErrorCode": 1007 } ``` ## Permissions Your API key must support your request in order to be successful. Sending an API request with an API key that does not support that request will result in an error response. Example: Error Response [Copy](javascript:void\(0\);) ``` { "statusCode": 403, "timestamp": "2025-11-19T09:37:43.012Z", "path": "/api/buildcache/clusters/ClusterA/stop?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": "You do not have the required permissions to use this API request", "ibErrorCode": 2005 } ``` ## Log Level Management The log level is used to provide more (or less) detail in your Incredibuild logs. API Log level actions can be done only on clusters. There are 5 log levels: Minimal, Basic (recommended), Intermediate, Extended, Detailed. **Example Request:** GET a cluster's log level ``` GET https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/LogLevel?coordinatorId={coordID}&version=1.5.0 ``` Response Example: [Copy](javascript:void\(0\);) ``` { "level": "Intermediate" } ``` **Example Request:** Modify a cluster's log level ``` PUT https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/LogLevel?coordinatorId={coordID}&version=1.5.0 ``` Example Body: [Copy](javascript:void\(0\);) ``` { "level": "Detailed" } ``` Response Example: [Copy](javascript:void\(0\);) ``` { "id": "ClusterA", "success": true } ``` **Example Request**: Attempt to modify a cluster log level to an invalid log level. ``` PUT https://{coordIP}:8000/api/buildcache/clusters/{clusterName}/LogLevel?coordinatorId={coordID}&version=1.5.0 ``` Send the PUT request, with a JSON document similar to the following example, as part of the request body. In this example, the requested level ("Invalid") is not a valid value. [Copy](javascript:void\(0\);) ``` { "level": "Invalid" } ``` Response Example: [Copy](javascript:void\(0\);) ``` { "statusCode": 400, "timestamp": "2025-11-19T09:56:38.984Z", "path": "/api/buildcache/clusters/ClusterA/LogLevel?coordinatorId=155B2F53-0834-4C21-B367-5C3E13FCE685&version=1.5.0", "message": " The property level has failed the following constraints: level must be one of the following values: Minimal, Basic, Intermediate, Extended, Detailed \n", "ibErrorCode": 9600 } ``` ## **Response Status Codes** This API uses standard REST API status codes.