Build Group API
This feature is only available in Incredibuild's Enterprise Plan.
Every API call must include a header with a key called client-api-key and the value of your API key. 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
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
{
"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
{
"buildGroups": [
{"buildGroup":"bg3","cloudEnabled":true}
]
}Example Response
{
"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
{
"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
{
"buildGroups": ["bg1","bg2","bg3"]
}Example Response
{
"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
{
"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
{
"newBuildGroup":"BG2",
"cloudEnabled":false
}Example Response
{
"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
[
{
"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
[
{
"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.
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
{
"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)
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:
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:
[
{
"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
POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{group}/clear?coordinatorId={coordinatorId}&version=1.0.0 { }Example Request:
POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/Dev/clear?coordinatorId={coordinatorId}&version=1.0.0 {}Example Response:
{
"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
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:
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:
[
{
"agentName": "desktop123",
"status": "OK"
},
{
"agentName": "desktop248",
"status": "OK"
},
]Build Group API Version 1.0.0
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
[
{
"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
[
{
"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.
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
{
"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)
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:
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:
[
{
"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
POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{group}/clear?coordinatorId={coordinatorId}&version=1.0.0 { }Example Request:
POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/Dev/clear?coordinatorId={coordinatorId}&version=1.0.0 {}Example Response:
{
"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
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:
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:
[
{
"agentName": "desktop123",
"status": "OK"
},
{
"agentName": "desktop248",
"status": "OK"
},
]