Agents

The /agents endpoint provides read-only access to MetaKraftwerk agents. Agents are client programs that connect to the MetaKraftwerk server via WebSocket to execute deployments and other automated tasks.

See Also

• Authentication — Required for all API requests
• Agents — Agent installation and configuration
• Agent Groups API — Logical grouping of agents

GET /api/v1/agents — Find Agents

Retrieve a list of agents, optionally filtered by name, status, or group.

Endpoint

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

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by agent name.
agent_id	string	No	Filter by agent UUID.
online	boolean	No	Filter by online status (true or false).
group_id	integer	No	Filter by agent group ID.
group	string	No	Filter by agent group name.

Response Schema

Returns an array of agent objects:

Field	Type	Description
id	integer	Unique agent ID.
agent_id	string	Agent UUID identifier.
name	string	Agent name.
deleted	boolean	Whether the agent is marked as deleted.
disabled	boolean	Whether the agent is disabled.
online	boolean	Whether the agent is currently connected.
group_id	integer	Agent group ID.

Examples

cURL

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

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

# Find by UUID
curl -X GET "https://app.metakraftwerk.com/api/v1/agents?agent_id=de058784-c9cc-448d-8e64-bfda70b314cc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find online agents
curl -X GET "https://app.metakraftwerk.com/api/v1/agents?online=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

JavaScript (Fetch)

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

const agents = await response.json();

Response Example

[
  {
    "id": 301,
    "agent_id": "de058784-c9cc-448d-8e64-bfda70b314cc",
    "name": "dev_md_agent",
    "deleted": false,
    "disabled": false,
    "online": false,
    "group_id": 1
  }
]

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated
404	Agent group not found	An agent group with the name 'X' does not exist!

---

GET /api/v1/agents/:id — Get Agent

Retrieve a single agent by its ID.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The agent ID.

Examples

cURL

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

JavaScript (Fetch)

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

const agent = await response.json();

Error Responses

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

---

POST /api/v1/agents — Create

Not implemented

PUT /api/v1/agents — Update

Not implemented

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

Not implemented

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

Not implemented