Agent Groups

The /agent_groups endpoint provides read-only access to agent groups. Agent groups are logical groupings of agents, allowing deployments to be assigned to a group rather than a specific agent.

See Also

• Authentication — Required for all API requests
• Agents — Agent installation and configuration
• Agents API — Individual agent endpoint

GET /api/v1/agent_groups — Find Agent Groups

Retrieve a list of agent groups.

Endpoint

GET https://app.metakraftwerk.com/api/v1/agent_groups

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by agent group name.

Response Schema

Returns an array of agent group objects:

Field	Type	Description
id	integer	Unique agent group ID.
name	string	Agent group name.
description	string	Description of the agent group.

Examples

cURL

# List all agent groups
curl -X GET "https://app.metakraftwerk.com/api/v1/agent_groups" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find by name
curl -X GET "https://app.metakraftwerk.com/api/v1/agent_groups?name=DEV_AGENTS" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

const response = await fetch(
  'https://app.metakraftwerk.com/api/v1/agent_groups?name=DEV_AGENTS',
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
);

const agentGroups = await response.json();

Response Example

[
  {
    "id": 1,
    "name": "DEV_AGENTS",
    "description": null
  }
]

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated

---

GET /api/v1/agent_groups/:id — Get Agent Group

Retrieve a single agent group by its ID.

Endpoint

GET https://app.metakraftwerk.com/api/v1/agent_groups/:id

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The agent group ID.

Examples

cURL

curl -X GET "https://app.metakraftwerk.com/api/v1/agent_groups/1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

const response = await fetch(
  'https://app.metakraftwerk.com/api/v1/agent_groups/1',
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
);

const agentGroup = await response.json();

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated
404	Agent group not found	No record found for id 'X'

---

POST /api/v1/agent_groups — Create

Not implemented

PUT /api/v1/agent_groups — Update

Not implemented

PATCH /api/v1/agent_groups/:id — Patch

Not implemented

DELETE /api/v1/agent_groups/:id — Remove

Not implemented