Agents API

8 operations. Paths are relative to the API host (http://localhost:5080 in local development). Every operation accepts an OIDC bearer token (Authorization: Bearer …) or a workspace API key (X-Api-Key: keel_live_…); errors are RFC 9457 Problem Details with a code (error codes). Permissions: matrix.

Method	Path	Summary
GET	/api/v1/workspaces/{workspaceId}/agents	Private agents of the workspace with their status (online from heartbeats).
POST	/api/v1/workspaces/{workspaceId}/agents	Create a private agent in a pool and its one-time enrollment token (shown once, single use, expires in 15 minutes).
GET	/api/v1/workspaces/{workspaceId}/agents/{agentId}	One private agent.
PATCH	/api/v1/workspaces/{workspaceId}/agents/{agentId}	Rename a private agent, move it to another pool or change its location (audited).
POST	/api/v1/workspaces/{workspaceId}/agents/{agentId}:revoke	Revoke a private agent: its certificate stops working at once and its pool work is re-queued for other members (audited).
PUT	/api/v1/workspaces/{workspaceId}/agents/{agentId}/release-channel	Set the release channel of an agent: stable, beta or pinned to a version; null follows its pool (audited).
GET	/api/v1/workspaces/{workspaceId}/agents/fleet	The agent version the control plane ships, the workspace's pools and the update commands (F22).
PUT	/api/v1/workspaces/{workspaceId}/agents/pools/{pool}/release-channel	Set the release channel every agent of a pool follows unless it has its own; null puts the pool on stable (audited).

ListAgents

GET /api/v1/workspaces/{workspaceId}/agents

Private agents of the workspace with their status (online from heartbeats).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Status	Description	Body
200	OK	AgentSummary[]

CreateAgent

POST /api/v1/workspaces/{workspaceId}/agents

Create a private agent in a pool and its one-time enrollment token (shown once, single use, expires in 15 minutes).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Request body (application/json): CreateAgentRequest

Field	Type	Notes
location	string?	F22 FR3: a location label, e.g. "Frankfurt DC".
name	string
pool	string?	F22 FR6: the pool the agent joins (default when empty).

Status	Description	Body
201	Created	AgentEnrollmentResponse

Response 201: AgentEnrollmentResponse

Field	Type	Notes
agentId	uuid
dockerCommand	string
expiresAt	date-time
helmCommand	string?	F22 packaging: the Helm install of the keel-agent chart.
name	string
pool	string?
serverUrl	string
token	string
version	string?
windowsCommand	string?	F22 packaging: the Windows service installer (PowerShell, as Administrator).

GetAgent

GET /api/v1/workspaces/{workspaceId}/agents/{agentId}

One private agent.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
agentId	path	uuid	yes

Status	Description	Body
200	OK	AgentSummary

Response 200: AgentSummary

Field	Type	Notes
capabilities	AgentCapabilities?
certificateExpiresAt	date-time?
certificateRotatedAt	date-time?
certificateThumbprint	string?
connection	string
createdAt	date-time
enrolledAt	date-time?
enrollmentExpiresAt	date-time?
hostname	string?
id	uuid
jobsRunning	int32
lastSeenAt	date-time?
location	string?
name	string
pool	string
revokedAt	date-time?
sourceCount	int32
status	AgentStatus	One of Pending, Active, Revoked
update	AgentUpdateSummary?
version	string?
versionStatus	AgentVersionSkew?

UpdateAgent

PATCH /api/v1/workspaces/{workspaceId}/agents/{agentId}

Rename a private agent, move it to another pool or change its location (audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
agentId	path	uuid	yes

Request body (application/json): UpdateAgentRequest

Field	Type	Notes
location	string?
name	string
pool	string?

Status	Description	Body
204	No Content	—

RevokeAgent

POST /api/v1/workspaces/{workspaceId}/agents/{agentId}:revoke

Revoke a private agent: its certificate stops working at once and its pool work is re-queued for other members (audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
agentId	path	uuid	yes

Status	Description	Body
204	No Content	—

SetAgentReleaseChannel

PUT /api/v1/workspaces/{workspaceId}/agents/{agentId}/release-channel

Set the release channel of an agent: stable, beta or pinned to a version; null follows its pool (audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
agentId	path	uuid	yes

Request body (application/json): SetReleaseChannelRequest

Field	Type	Notes
channel	string?
pinnedVersion	string?

Status	Description	Body
204	No Content	—

GetAgentFleet

GET /api/v1/workspaces/{workspaceId}/agents/fleet

The agent version the control plane ships, the workspace's pools and the update commands (F22).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Status	Description	Body
200	OK	AgentFleetResponse

Response 200: AgentFleetResponse

Field	Type	Notes
betaVersion	string?	M12.2: the version behind the beta channel.
dockerUpdateCommand	string
helmUpdateCommand	string
image	string
latestVersion	string
poolChannels	AgentPoolChannelInfo[]?	M12.2: pools with a release channel set.
pools	string[]
releases	AgentReleaseInfo[]?	M12.2: versions with packages (what can be pinned).
selfUpdate	boolean	M12.2: releases are signed, so Windows service and binary installs update themselves.
stableVersion	string?	M12.2: the version behind the stable channel.
windowsUpdateCommand	string

SetAgentPoolChannel

PUT /api/v1/workspaces/{workspaceId}/agents/pools/{pool}/release-channel

Set the release channel every agent of a pool follows unless it has its own; null puts the pool on stable (audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
pool	path	string	yes

Request body (application/json): SetReleaseChannelRequest

Field	Type	Notes
channel	string?
pinnedVersion	string?

Status	Description	Body
204	No Content	—