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.

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

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

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

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

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

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