List a custom agent's definition versions
Lists the agent definitions a custom agent's states named within the window the days parameter sets (default 30 days, at most 90), newest first: one row per definition however many times Viper signed a new state for it, under however many keys (revoked ones included) and sub-agents, with the framework it names, the sub-agents whose requests ran it ("" for the agent itself), when it was first and last seen, how many distinct states named it and how many requests ran it, the keys and configurations those gave, the newest state that named it, and whether the agent's newest state names it (current). Read a definition through state-cids/{latest_state_cid}/blobs/{definition_cid}. A change to the definition, a sub-agent, a skill's files or memory the agent can't change is a new definition. The current definition is always listed, after the others, even when the window or the limit would leave it out, and is then counted over all its requests. recorded is false when the gateway has recorded no definition for the agent: it isn't a custom agent, its requests all predate the gateway recording them, or no state it presented named a definition the gateway could record. Readable by an admin and by users bound to the agent.
https://<host>/api/v1/agents/{agentId}/definitionscurl --request GET \
--url 'https://<host>/api/v1/agents/{agentId}/definitions' \
--header 'Authorization: Bearer <token>'const response = await fetch("https://<host>/api/v1/agents/{agentId}/definitions", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
const data = await response.json();interface AgentDefinitionListResponse {
agent_id?: string;
correlation_id?: string;
items?: Record<string, unknown>[];
recorded?: boolean;
}
const response = await fetch("https://<host>/api/v1/agents/{agentId}/definitions", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
const data: AgentDefinitionListResponse = await response.json();import requests
response = requests.get(
"https://<host>/api/v1/agents/{agentId}/definitions",
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/{agentId}/definitions", 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/{agentId}/definitions"))
.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/{agentId}/definitions");
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/{agentId}/definitions');
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/{agentId}/definitions")
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/{agentId}/definitions")
.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
Path parameters
| Name | Type | Description |
|---|---|---|
agentIdrequired | string | Agent ID |
Query parameters
| Name | Type | Description |
|---|---|---|
days | integer | How many days back to look (default 30, max 90) |
limit | integer | Most definitions to list (default 20, max 100) |
Responses
200OK
agent_idstringcorrelation_idstringitemsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentDefinitionSummary[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentDefinitionSummaryconfiguration_cidsstring[]ConfigurationCIDs are the configurations its states gave; one, unless how the gateway derives configurations changed while it ran.
currentbooleanCurrent is whether the agent's newest state names it.
definition_cidstringfirst_seen_atstringframeworkagentconfig.FrameworkShow agentconfig.Framework
namestringpackagesobjectShow properties
Map of
string
key_didsstring[]last_seen_atstringlatest_state_cidstringrequestsintegerstatesintegersub_agentsstring[]
recordedboolean
{
"agent_id": "string",
"correlation_id": "string",
"items": [
{
"configuration_cids": [
"string"
],
"current": true,
"definition_cid": "string",
"first_seen_at": "string",
"framework": {
"name": "string",
"packages": {
"key": "string"
}
},
"key_dids": [
"string"
],
"last_seen_at": "string",
"latest_state_cid": "string",
"requests": 0,
"states": 0,
"sub_agents": [
"string"
]
}
],
"recorded": true
}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"
}