> ## 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](/windows/10.31.2/pricing-plans).
Every API call must include a header with a key called **client-api-key** and the value of your [API key](/windows/10.31.2/api-keys). 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.
## Build Group API Version 1.2.0
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":"","cloudEnabled":}
]
}
```
**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"
}
]
}
```
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": ["",""]
}
```
**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"
}
]
}
```
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":"",
"cloudEnabled":
}
```
**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"
}
```
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
}
]
```
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",
}
]
```
Returns the details of one or more Agents. For more information about what these agent details mean, see [Viewing Agents](/windows/10.31.2/coordinator-agents-list#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"
}
]
}
```
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"
}
]
```
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
}
```
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
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
}
]
```
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",
}
]
```
Returns the details of one or more Agents. For more information about what these agent details mean, see [Viewing Agents](/windows/10.31.2/coordinator-agents-list#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"
}
]
}
```
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"
}
]
```
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
}
```
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"
},
]
```