Build Cache API - IncrediBuild Documentation

Last updated on Dec 25, 2025 This feature is only available in Incredibuild’s Enterprise Plan. 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 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. 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:

IB Coordinator IP Address/Hostname - The IP address or hostname of the Coordinator.
Coordinator UI Port - The port number defined during installation. By default, this is 8000.
clusters/nodes - Determines whether the action is on an entire cluster or is on a specific node.
cluser/nodeName - The cluster or node name being queried / acted upon.
action - stop, start, restart, clear
1. stop service
2. start service
3. restart service
4. clear cache
5. LogLevel (Cluster only)
Coordinator ID - The ID assigned by Incredibuild to your Coordinator. You can view this in the Coordinator Manager > Settings > API Access area.\
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 - POST

Example Request: Stop

POST https://{coordIP}:8000/api/buildcache/nodes/{nodeName}/stop?coordinatorId={coordID}&version=1.5.0

Example Response Copy

    {
        "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

    {
        "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

{
             "nodes": ["node_0", "node_1"]  
}

Example body: Copy

{
             "nodes": ["AW9222_H_1_0", "AW9222_H_1_1"]  
}

Example Response: Copy

    {
                "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

    {

            "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",
            "ibErrorCode": 9600        
    }

Example Request: Stop an invalid node

POST https://{coordIP}:8000/api/buildcache/nodes/InvalidNode/stop?coordinatorId={coordID}&version=1.5.0

Example Response: Copy

    {

            "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

    {
        "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

    {
        "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

    {

            "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

    {

            "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

[
    {
        "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

[
    {
        "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

{
    "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

[
    {
        "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

{
    "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

{
    "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

{
    "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

{
    "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:

{
    "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

{
             "level": "Detailed"
}

Response Example

{
    "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

{
             "level": "Invalid"
}

Response Example:

{
    "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.

​API Key and Syntax

​Support Matrix

​POST Actions on Nodes

​HTTP Method - POST

​POST Actions on Clusters

​HTTP Method - POST

​Data Retrieval

​Authentication & Licenses

​Permissions

​Log Level Management

​Response Status Codes

API Key and Syntax

Support Matrix

POST Actions on Nodes

HTTP Method - POST

POST Actions on Clusters

HTTP Method - POST

Data Retrieval

Authentication & Licenses

Permissions

Log Level Management

Response Status Codes