> ## 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 Group API

Last updated on Dec 22, 2025

This feature is only available in Incredibuild's [Enterprise Plan](https://docs.incredibuild.com/windows/10.38.1/pricing-plans.md).

Every API call must include a header with a key called **client-api-key** and the value of your [API key](https://docs.incredibuild.com/windows/10.38.1/api-keys.md). All APIs are case sensitive.

The following are descriptions of items in the API's calls below:

* **Coordinator IP Address/Hostname** – the IP address or hostname of the Coordinator.

* **Coordinator UI Port** – the port number you defined during installation. By default, this is 8000.

* **Version** - the version of our API. The latest version is 1.2.0, but this API also supports 1.0.0. If you do not specify a version in the API call, the lowest supported version will be used.

* **Coordinator ID** - The ID assigned by Incredibuild to your Coordinator. You can view this in the **Coordinator Manager** > **Settings** > **API Access** area.

  ![](https://mintcdn.com/incredibuild-docs-migrated/ZOEqdwyRwGqk-nbn/images/windows/_shared/windows/api_key_coord_id.png?fit=max\&auto=format\&n=ZOEqdwyRwGqk-nbn\&q=85\&s=f4fde6b5d82e6cd61ff79e5741d84367)

## Build Group API Version 1.2.0

> [accordion] Add Build Group
>
> Creates a new Build Group. You specify the name of the new Build Group, and whether cloud agents are enabled in the body of the request.
>
> **Request Syntax**
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/add?coordinatorId={coordinatorId}&version=1.3.0
> ```
>
> **Body Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> { 
>     "buildGroups": [
>            {"buildGroup":"<build group name>","cloudEnabled":<true|false>}
>                    ]
> }
> ```
>
> **Example request:**
>
> ```
> POST https://w_qa_1268_c_0:8000/api/build-groups/add?coordinatorId=0F0EA79D-3C8B-4DC5-9C2E-90D1DF0AD24E&version=1.3.0
> ```
>
> **Example Body**
>
> [Copy](javascript:void\(0\);)
>
> ```
> { 
>                 "buildGroups": [
>                                {"buildGroup":"bg3","cloudEnabled":true}
>                 ]
>
> }
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>     "totalRecords": 1,
>     "failed": 0,
>     "success": 1,
>     "buildGroups": [
>         {
>             "group": "bg3",
>             "status": "OK"
>         }
>     ]
> }
> ```

> [accordion] Delete Build Group
>
> Deletes one or more existing Build Groups.
>
> **Request Syntax**
>
> ```
> DELETE https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/delete?coordinatorId={coordinatorId}&version=1.3.0
> ```
>
> **Body Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>     "buildGroups": ["<name of first build group to delete>","<additional build gruops to delete>"]
> }
> ```
>
> **Example request:**
>
> ```
> DELETE https://w_qa_1268_c_0:8000/api/build-groups/delete?coordinatorId=0F0EA79D-3C8B-4DC5-9C2E-90D1DF0AD24E&version=1.3.0
> ```
>
> **Example Body**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>     "buildGroups": ["bg1","bg2","bg3"]
> }
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> { 
>     "totalRecords": 3,
>     "failed": 2,
>     "success": 1,
>     "buildGroups": [
>         {
>             "group": "bg1",
>             "message": "That Build Group does not exist",
>             "status": "fail"
>         },
>         {
>             "group": "bg2",
>             "message": "That Build Group does not exist",
>             "status": "fail"
>         },
>         {
>             "group": "bg3",
>             "status": "OK"
>         }
>     ]
> }
> ```

> [accordion] Edit Build Group
>
> Edits an existing Build Group by changing the name and/or whether cloud agents are enabled.
>
> **Request Syntax**
>
> ```
> PUT https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{BG name to edit}/edit?coordinatorId={coordinatorId}&version=1.3.0
> ```
>
> **Body Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>                 "newBuildGroup":"<Build Group Name>",
>                 "cloudEnabled":<true|false>
> }
> ```
>
> **Example request:**
>
> ```
> PUT https://w_qa_1268_c_0:8000/api/build-groups/BG4/edit?coordinatorId=0F0EA79D-3C8B-4DC5-9C2E-90D1DF0AD24E&version=1.3.0
> ```
>
> **Example Body**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>                 "newBuildGroup":"BG2",
>                 "cloudEnabled":false
> }
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> { 
>     "group": "BG2",
>     "status": "OK"
> }
> ```

> [accordion] Get List of Build Groups
>
> Returns a list of all Build Groups in a specific Coordinator.
>
> **Request Syntax**
>
> ```
> GET https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups?coordinatorId={coordinatorId}&version=1.3.0
> ```
>
> **Example request:**
>
> ```
> GET https://coordinatorPc:8000/api/build-groups?coordinatorId=00000000-0000-0000-0000-000000000000&version=1.3.0
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>     {
>         "group": "Default",
>         "agentCount": 1
>     },
>     {
>         "group": "QA-2",
>         "agentCount": 6
>     },
>     {
>         "group": "QA-3",
>         "agentCount": 4
>     }
> ]
> ```

> [accordion] Get Agents in Build Group
>
> Return a list of all the Agents in a specific Build Group.
>
> **Request Syntax**
>
> ```
> GET https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{build group name}/agents?coordinatorId={coordinatorId}&version=1.3.0
> ```
>
> **Example Request:**
>
> ```
> GET https://coordinatorPc:8000/api/build-groups/dev-group/agents?coordinatorId=00000000-0000-0000-0000-000000000000&version=1.3.0
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>     {
>         "name": "AgentSmith",       
>         "ip": "127.0.0.1"
>     },
>     {
>         "name": "AgentBill",      
>         "ip": "127.0.0.2",       
>     }
> ]
> ```

> [accordion] Get Agents Details
>
> Returns the details of one or more Agents. For more information about what these agent details mean, see [Viewing Agents](https://docs.incredibuild.com/windows/10.38.1/coordinator-agents-list.md#View).
>
> **Request Syntax**
>
> ```
> GET https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/agents?coordinatorId={coordinatorId}&version=1.0.0&agents=[{agent name1},{agent name2}]
> ```
>
> **Example Request:**
>
> ```
> GET https://coordinatorPc:8000/api/agents?agents=[AgentSmith,NeoHelper,SpoonHelper]&coordinatorId=00000000-0000-0000-0000-000000000000&version=1.3.0
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>     "agentsInRequest": 3,
>     "agentsInResults": 2,
>     "agentsNotFound": 1,
>     "agentsDetails": [
>         {
>             "name": "AgentSmith",
>             "id": " AgentSmith ",
>             "buildGroup": "dev-group",
>             "ip": "127.0.0.1",
>             "status": "Ready"
>         },
>         {
>             "name": "NeoHelper",
>             "id": " NeoHelper",
>             "buildGroup": "devops",
>             "ip": "100.6.6.6",
>             "status": "Ready"
>         }
>     ]
> }
> ```

> [accordion] Assign Agents to Build Group
>
> Assign one or more Agents to an existing Build Group. You cannot perform the Agent Assignment action if one of the Agents is participating in a build or is offline.
>
> **Request Syntax (with example agents)**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{build group name}/agents/add?coordinatorId={coordinatorId}&version=1.0.0
> {
>     "agents": ["Agent007", "test"]
> }
> ```
>
> **Example Request:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://coordinatorPc:8000/api/build-groups/cool-guys/agents?coordinatorId=00000000-0000-0000-0000-000000000000&version=1.0.0
> {
>     "agents": ["AgentJay", "AgentBob","AgentDante"]
> }
> ```
>
> **Example Response:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>     {
>         "agentName": "AgentJay",
>         "status": "OK"
>     },
>     {
>         "agentName": "AgentBob",
>         "status": "OK"
>     },
>     {
>         "agentName": "AgentDante",
>         "status": "fail",
>         "message": "Agent not found"
>     }
> ]
> ```

> [accordion] Clear All Agents from Build Group
>
> Removes all Agents from a specified Build Group. The Agents are reassigned to the **Default** Build Group.
>
> If an Agent is offline, the Clear action may appear to complete successfully, but the offline Agent remains in the original Build Group.
>
> **Request Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{group}/clear?coordinatorId={coordinatorId}&version=1.0.0 { }
> ```
>
> **Example Request:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/Dev/clear?coordinatorId={coordinatorId}&version=1.0.0 {}
> ```
>
> **Example Response:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>     "clearedGroupName": "Dev",
>     "agentsAffected": 2
> }
> ```

> [accordion] Unassign Agents from Build Group
>
> Removes the Agents you specify from whatever build groups they are assigned to. They are the reassigned to the **Default** Build Group.
>
> You cannot perform the Clear action, if one or more Agents in the specified Build Group are currently participating in a build or is offline. If an Agent is offline, the Clear action may appears to complete successfully, but the offline Agent remains in the original Build Group.
>
> **Request Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/agents/clear?coordinatorId={coordinatorId}&version=1.0.0
> {
>     "agents": ["agentname1", "agentname2"]
> }
> ```
>
> **Example Request:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/agents/clear?coordinatorId={coordinatorId}&version=1.0.0
> {
>     "agents": ["desktop123", "desktop248"]
> }
> ```
>
> **Example Response:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>     {
>         "agentName": "desktop123",
>         "status": "OK"
>     },
>     {
>         "agentName": "desktop248",
>         "status": "OK"
>     },
> ]
> ```

## Build Group API Version 1.0.0

> [accordion] Get List of Build Groups
>
> Returns a list of all Build Groups in a specific Coordinator.
>
> **Request Syntax**
>
> ```
> GET https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups?coordinatorId={coordinatorId}&version=1.0.0
> ```
>
> **Example request:**
>
> ```
> GET https://coordinatorPc:8000/api/build-groups?coordinatorId=00000000-0000-0000-0000-000000000000&version=1.0.0
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>                         {
>                         "group": "Default",
>                         "agentCount": 1
>                         },
>                         {
>                         "group": "QA-2",
>                         "agentCount": 6
>                         },
>                         {
>                         "group": "QA-3",
>                         "agentCount": 4
>                         }
>                     ]
> ```

> [accordion] Get Agents in Build Group
>
> Return a list of all the Agents in a specific Build Group.
>
> **Request Syntax**
>
> ```
> GET https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{build group name}/agents?coordinatorId={coordinatorId}&version=1.0.0
> ```
>
> **Example Request:**
>
> ```
> GET https://coordinatorPc:8000/api/build-groups/dev-group/agents?coordinatorId=00000000-0000-0000-0000-000000000000&version=1.0.0
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>                         {
>                         "name": "AgentSmith",       
>                         "ip": "127.0.0.1"
>                         },
>                         {
>                         "name": "AgentBill",      
>                         "ip": "127.0.0.2",       
>                         }
>                     ]
> ```

> [accordion] Get Agents Details
>
> Returns the details of one or more Agents. For more information about what these agent details mean, see [Viewing Agents](https://docs.incredibuild.com/windows/10.38.1/coordinator-agents-list.md#View).
>
> **Request Syntax**
>
> ```
> GET https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/agents?coordinatorId={coordinatorId}&version=1.0.0&agents=[{agent name1},{agent name2}]
> ```
>
> **Example Request:**
>
> ```
> GET https://coordinatorPc:8000/api/agents?agents=[AgentSmith,NeoHelper,SpoonHelper]&coordinatorId=00000000-0000-0000-0000-000000000000&version=1.0.0
> ```
>
> **Example Response**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>                         "agentsInRequest": 3,
>                         "agentsInResults": 2,
>                         "agentsNotFound": 1,
>                         "agentsDetails": [
>                         {
>                         "name": "AgentSmith",
>                         "id": " AgentSmith ",
>                         "buildGroup": "dev-group",
>                         "ip": "127.0.0.1",
>                         "status": "Ready"
>                         },
>                         {
>                         "name": "NeoHelper",
>                         "id": " NeoHelper",
>                         "buildGroup": "devops",
>                         "ip": "100.6.6.6",
>                         "status": "Ready"
>                         }
>                         ]
>                     }
> ```

> [accordion] Assign Agents to Build Group
>
> Assign one or more Agents to an existing Build Group. You cannot perform the Agent Assignment action if one of the Agents is participating in a build or is offline.
>
> **Request Syntax (with example agents)**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{build group name}/agents/add?coordinatorId={coordinatorId}&version=1.0.0
>                         {
>                         "agents": ["YAIRMAYER8DBB", "test"]
>                     }
> ```
>
> **Example Request:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://coordinatorPc:8000/api/build-groups/cool-guys/agents?coordinatorId=00000000-0000-0000-0000-000000000000&version=1.0.0
>                         {
>                         "agents": ["AgentJay", "AgentBob","AgentDante"]
>                     }
> ```
>
> **Example Response:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>                         {
>                         "agentName": "AgentJay",
>                         "status": "OK"
>                         },
>                         {
>                         "agentName": "AgentBob",
>                         "status": "OK"
>                         },
>                         {
>                         "agentName": "AgentDante",
>                         "status": "fail",
>                         "message": "Agent not found"
>                         }
>                     ]
> ```

> [accordion] Clear All Agents from Build Group
>
> Removes all Agents from a specified Build Group. The Agents are reassigned to the **Default** Build Group.
>
> If an Agent is offline, the Clear action may appear to complete successfully, but the offline Agent remains in the original Build Group.
>
> **Request Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{group}/clear?coordinatorId={coordinatorId}&version=1.0.0 { }
> ```
>
> **Example Request:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/Dev/clear?coordinatorId={coordinatorId}&version=1.0.0 {}
> ```
>
> **Example Response:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> {
>                         "clearedGroupName": "Dev",
>                         "agentsAffected": 2
>                     }
> ```

> [accordion] Unassign Agents from Build Group
>
> Removes the Agents you specify from whatever build groups they are assigned to. They are the reassigned to the **Default** Build Group.
>
> You cannot perform the Clear action, if one or more Agents in the specified Build Group are currently participating in a build or is offline. If an Agent is offline, the Clear action may appears to complete successfully, but the offline Agent remains in the original Build Group.
>
> **Request Syntax**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/agents/clear?coordinatorId={coordinatorId}&version=1.0.0
>                         {
>                         "agents": ["agentname1", "agentname2"]
>                     }
> ```
>
> **Example Request:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/agents/clear?coordinatorId={coordinatorId}&version=1.0.0
>                         {
>                         "agents": ["desktop123", "desktop248"]
>                     }
> ```
>
> **Example Response:**
>
> [Copy](javascript:void\(0\);)
>
> ```
> [
>                         {
>                         "agentName": "desktop123",
>                         "status": "OK"
>                         },
>                         {
>                         "agentName": "desktop248",
>                         "status": "OK"
>                         },
>                     ]
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.