Build Group API

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. Currently there is only one version: 1.0.0.

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

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

Copy 
{
    "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 
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 
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 
[
    {
        "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 
POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/{group}/clear?coordinatorId={coordinatorId}&version=1.0.0
{
}

Example Request: 

Copy 
POST https://{Coordinator IP Address/Hostname}:{Web Access Port}/api/build-groups/Dev/clear?coordinatorId={coordinatorId}&version=1.0.0
{
}

Example Response:

Copy 
{
    "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 
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 
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 
[
    {
        "agentName": "desktop123",
        "status": "OK"
    },
    {
        "agentName": "desktop248",
        "status": "OK"
    },
]