Get project agent
Returns a project-scoped agent only when it has membership evidence for this project: a registered agent, by its ID or one of its keys' DIDs, or a DID no agent holds. It lists every key when a membership names the agent, and otherwise only the keys memberships name. Each key says how it joined the agent, never who added it.
https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}curl --request GET \
--url 'https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}' \
--header 'Authorization: Bearer <token>'const response = await fetch("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
const data = await response.json();interface ProjectAgentDetailResponseDoc {
correlation_id?: string;
item?: Record<string, unknown>;
}
const response = await fetch("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
const data: ProjectAgentDetailResponseDoc = await response.json();import requests
response = requests.get(
"https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}",
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/projects/{project_uuid}/agents/{agent_id}", 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/projects/{project_uuid}/agents/{agent_id}"))
.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/projects/{project_uuid}/agents/{agent_id}");
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/projects/{project_uuid}/agents/{agent_id}');
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/projects/{project_uuid}/agents/{agent_id}")
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/projects/{project_uuid}/agents/{agent_id}")
.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 |
|---|---|---|
project_uuidrequired | string | Guardian project UUID |
agent_idrequired | string | Gateway agent ID, or a DID |
Responses
200OK
correlation_idstringiteminternal_controlhttp.projectAgentDetailDocShow internal_controlhttp.projectAgentDetailDoc
agent_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
current_configurationobjectdid_sourcestringdisplay_namestringframeworkobjectThe framework of the definition the agent's newest state, in any project, names, as app_type is; a project's own current definition is on its definitions route
Show properties
namestringpackagesobjectShow properties
Map of
string
keysgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentKey[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentKeyadded_bystringWho added it; told only to an admin and the agent's operators
added_by_api_key_idstringThe API key's public ID; told only to an admin and the agent's operators
added_by_emailstringTheir email; told only to an admin and the agent's operators
added_viastring (enum)AddedVia is how the key joined its agent: registration_token, api_key or control_plane; empty when no record of it survives. AddedBy is the subject of whoever added it, the registering principal or the admin, and AddedByAPIKeyID the API key's public ID.
One of
registration_tokenapi_keycontrol_planecreated_atstringdidstringstatusstringupdated_atstring
last_activity_atstringlogs_supportedbooleanmembership_evidenceinternal_controlhttp.projectAgentMembershipEvidenceDoc[]Show properties
Array of
internal_controlhttp.projectAgentMembershipEvidenceDoccredential_idstringcredential_statusinternal_controlhttp.projectAgentCredentialStatusDoc[]Show properties
Array of
internal_controlhttp.projectAgentCredentialStatusDocidstringrawobjectShow properties
Map of
anystatus_list_credentialstringstatus_list_indexstringstatus_purposestringtypestring
credential_status_checked_atstringgateway_agent_idstringissuer_didstringlast_verified_atstringobserved_atstringproject_urnstringproject_uuidstringrolesstring[]sourcestringsource_refsinternal_controlhttp.projectAgentSourceRefsDocShow internal_controlhttp.projectAgentSourceRefsDoc
credential_idstringsource_cidstringstatement_cidstringstatement_idstring
status_check_attempted_atstringstatus_resolutioninternal_controlhttp.projectAgentStatusResolutionDocShow internal_controlhttp.projectAgentStatusResolutionDoc
checked_atstringmetadataobjectShow properties
Map of
anyrevokedboolean
subject_didstringThe credential's subject: a DID or the agent's urn:uuid
valid_fromstringvalid_untilstringvalidation_errorsinternal_controlhttp.projectAgentValidationErrorDoc[]Show properties
Array of
internal_controlhttp.projectAgentValidationErrorDoccodestringfieldstringmessagestring
validation_statusstring
membership_statestringprimary_didstringprimary_user_display_namestringstate_cids_supportedbooleanstatusstringsubject_didstringThe row's identity: the agent's ID (its urn:uuid) for a registered agent, whether its memberships name the agent or its keys, or the DID no agent holds
throughputinteger[]
{
"correlation_id": "string",
"item": {
"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"
}
],
"current_configuration": {},
"did_source": "string",
"display_name": "string",
"framework": {
"name": "string",
"packages": {
"key": "string"
}
},
"keys": [
{
"added_by": "string",
"added_by_api_key_id": "string",
"added_by_email": "string",
"added_via": "registration_token",
"created_at": "string",
"did": "string",
"status": "string",
"updated_at": "string"
}
],
"last_activity_at": "string",
"logs_supported": true,
"membership_evidence": [
{
"credential_id": "string",
"credential_status": [
{
"id": "string",
"raw": {
"key": null
},
"status_list_credential": "string",
"status_list_index": "string",
"status_purpose": "string",
"type": "string"
}
],
"credential_status_checked_at": "string",
"gateway_agent_id": "string",
"issuer_did": "string",
"last_verified_at": "string",
"observed_at": "string",
"project_urn": "string",
"project_uuid": "string",
"roles": [
"string"
],
"source": "string",
"source_refs": {
"credential_id": "string",
"source_cid": "string",
"statement_cid": "string",
"statement_id": "string"
},
"status_check_attempted_at": "string",
"status_resolution": {
"checked_at": "string",
"metadata": {
"key": null
},
"revoked": true
},
"subject_did": "string",
"valid_from": "string",
"valid_until": "string",
"validation_errors": [
{
"code": "string",
"field": "string",
"message": "string"
}
],
"validation_status": "string"
}
],
"membership_state": "string",
"primary_did": "string",
"primary_user_display_name": "string",
"state_cids_supported": true,
"status": "string",
"subject_did": "string",
"throughput": [
0
]
}
}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"
}503Service Unavailable
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}