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.3.0, but this API also supports 1.2.0 and 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.

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

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

{ 
                "buildGroups": [
                               {"buildGroup":"bg3","cloudEnabled":true}
                ]

}

Example Response

Copy

{
    "totalRecords": 1,
    "failed": 0,
    "success": 1,
    "buildGroups": [
        {
            "group": "bg3",
            "status": "OK"
        }
    ]
}

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

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

{
    "buildGroups": ["bg1","bg2","bg3"]
}

Example Response

Copy

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

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

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

{
                "newBuildGroup":"BG2",
                "cloudEnabled":false
}

Example Response

Copy

{ 
    "group": "BG2",
    "status": "OK"
}

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

[
    {
        "group": "Default",
        "agentCount": 1
    },
    {
        "group": "QA-2",
        "agentCount": 6
    },
    {
        "group": "QA-3",
        "agentCount": 4
    }
]

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

[
    {
        "name": "AgentSmith",       
        "ip": "127.0.0.1"
    },
    {
        "name": "AgentBill",      
        "ip": "127.0.0.2",       
    }
]

Get Agents Details

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

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

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"
    }
]

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

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
}

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

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"
    },
]