List agents
Lists registry agents. An admin sees every agent and anyone else the agents they are bound to. An API key must name project_uuid and needs view_project_data on that project.
https://<host>/api/v1/agentscurl --request GET \
--url 'https://<host>/api/v1/agents' \
--header 'Authorization: Bearer <token>'const response = await fetch("https://<host>/api/v1/agents", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
const data = await response.json();interface ListAgentsResponse {
activity_window?: string;
correlation_id?: string;
items?: Record<string, unknown>[];
total_count?: number;
window_end?: string;
window_start?: string;
}
const response = await fetch("https://<host>/api/v1/agents", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
const data: ListAgentsResponse = await response.json();import requests
response = requests.get(
"https://<host>/api/v1/agents",
headers={
"Authorization": "Bearer <token>",
},
)
response.raise_for_status()
print(response.json())package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://<host>/api/v1/agents", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer <token>")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(res.Status, string(data))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://<host>/api/v1/agents"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());
}
}using System.Net.Http.Headers;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://<host>/api/v1/agents");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");<?php
$ch = curl_init('https://<host>/api/v1/agents');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status . " " . $response . PHP_EOL;require "net/http"
uri = URI("https://<host>/api/v1/agents")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer <token>"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.request(request)
end
puts "#{response.code} #{response.body}"// Cargo.toml dependencies: reqwest, tokio (features "full")
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = reqwest::Client::new()
.get("https://<host>/api/v1/agents")
.header("Authorization", "Bearer <token>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Ok(())
}Authorizations
BearerAuth· API key in header "Authorization" — Type "Bearer" followed by a space and a sign-in token: a Guardian Platform JWT, or an OIDC ID token in a standalone deployment.ApiKeyAuth· API key in header "Authorization" — Type "Bearer" followed by a space and a Guardian Platform API key. Project-scoped routes and registration tokens check the key's scopes and project binding. Per-agent routes accept a key bound to no project that has empty scopes or full access, which acts as its holder, or a scope for what the route does: submit_agent_assessments reads an agent (its detail, configurations, state history and the files a state references, definitions, tools and operating profile, as its assessments rest on), view_agent_certifications reads its certifications, and manage_programs or review_agent_assessments attach a certification. A state's raw snapshot and findings, its audit exchanges and plugin events, and saving its operating profile take full access. A scope counts only while the key's holder still holds that permission in the key's organization, which auth-service reports as keyHeldScopes. A key never acts as an admin, so its holder's binding to the agent still decides.
Parameters
Query parameters
| Name | Type | Description |
|---|---|---|
status | string (enum) | Status filter One of |
q | string | Search query |
project_uuid | string | Filter to agents ever associated with this project, any status; requires view_project_data. Required when authenticating with an API key |
user | string[] | Primary user display names; matches any |
agent_type | string[] | Agent types; matches any, and __unlabeled__ matches agents with no type |
framework | string[] | Custom agents' frameworks, as their definitions name them (langgraph, deepagents, …); matches any |
last_active | string (enum)[] | Last-active categories; matches any |
sort_by | string (enum) | Sort field; throughput requires include=throughput One of |
sort_dir | string (enum) | Sort direction One of |
limit | integer | Page size Default |
offset | integer | Offset Default |
include | string (enum) | Extra data to include One of |
has_profile | boolean | Only agents with a current operating profile. With an API key, needs one bound to no project, with empty scopes, * or submit_agent_assessments, as reading a profile does; any other key gets 403 |
Responses
200OK
activity_windowstringcorrelation_idstringitemsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentListItem[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentListItemactive_key_countintegeractive_user_binding_countintegeragent_idstringapp_typestringbadgesgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadge[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadgedescriptionstringfirst_observed_atstringkeystringlabelstringlast_observed_atstringmetadataobjectShow properties
Map of
anymetadata_typestringplugin_idstringstatusstringsubject_didstring
created_atstringdid_sourcestringdisplay_namestringframeworkobjectFramework is the framework named by the definition the agent's newest state names, as the definition gives it, read from the verified state rather than the app type a request declares. It is nil when the newest state names no definition (another app type, or recorded before the gateway recorded definitions) or the gateway couldn't record the definition's framework.
Show properties
namestringpackagesobjectShow properties
Map of
string
last_audit_atstringprimary_didstringprimary_user_display_namestringprojectsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProject[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProjectproject_urnstringproject_uuidstringvalid_fromstringvalid_untilstringvalidation_statusstring
statusstringthroughputinteger[]total_audit_eventsintegerupdated_atstring
total_countintegerwindow_endstringwindow_startstring
{
"activity_window": "string",
"correlation_id": "string",
"items": [
{
"active_key_count": 0,
"active_user_binding_count": 0,
"agent_id": "string",
"app_type": "string",
"badges": [
{
"description": "string",
"first_observed_at": "string",
"key": "string",
"label": "string",
"last_observed_at": "string",
"metadata": {
"key": null
},
"metadata_type": "string",
"plugin_id": "string",
"status": "string",
"subject_did": "string"
}
],
"created_at": "string",
"did_source": "string",
"display_name": "string",
"framework": {
"name": "string",
"packages": {
"key": "string"
}
},
"last_audit_at": "string",
"primary_did": "string",
"primary_user_display_name": "string",
"projects": [
{
"project_urn": "string",
"project_uuid": "string",
"valid_from": "string",
"valid_until": "string",
"validation_status": "string"
}
],
"status": "string",
"throughput": [
0
],
"total_audit_events": 0,
"updated_at": "string"
}
],
"total_count": 0,
"window_end": "string",
"window_start": "string"
}400Bad Request
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}401Unauthorized
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}403Forbidden
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}404Not Found
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}500Internal Server Error
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}