EQTY LabDocs

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.

gethttps://<host>/api/v1/agents
bash
curl --request GET \
  --url 'https://<host>/api/v1/agents' \
  --header 'Authorization: Bearer <token>'
javascript
const response = await fetch("https://<host>/api/v1/agents", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();
typescript
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();
python
import requests

response = requests.get(
    "https://<host>/api/v1/agents",
    headers={
        "Authorization": "Bearer <token>",
    },
)
response.raise_for_status()
print(response.json())
go
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))
}
java
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());
    }
}
csharp
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
<?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;
ruby
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}"
rust
// 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

NameTypeDescription
statusstring (enum)

Status filter

One ofactiverevokedderegistered

qstring

Search query

project_uuidstring

Filter to agents ever associated with this project, any status; requires view_project_data. Required when authenticating with an API key

userstring[]

Primary user display names; matches any

agent_typestring[]

Agent types; matches any, and __unlabeled__ matches agents with no type

frameworkstring[]

Custom agents' frameworks, as their definitions name them (langgraph, deepagents, …); matches any

last_activestring (enum)[]

Last-active categories; matches any

sort_bystring (enum)

Sort field; throughput requires include=throughput

One ofdisplay_nameprimary_user_display_namelast_audit_atcreated_atupdated_atthroughput

sort_dirstring (enum)

Sort direction

One ofascdesc

limitinteger

Page size

Default 25

offsetinteger

Offset

Default 0

includestring (enum)

Extra data to include

One ofthroughput

has_profileboolean

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

application/json
  • activity_windowstring
  • correlation_idstring
  • itemsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentListItem[]
    Show properties

    Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentListItem

    • active_key_countinteger
    • active_user_binding_countinteger
    • agent_idstring
    • app_typestring
    • badgesgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadge[]
      Show properties

      Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadge

      • descriptionstring
      • first_observed_atstring
      • keystring
      • labelstring
      • last_observed_atstring
      • metadataobject
        Show properties

        Map of any

      • metadata_typestring
      • plugin_idstring
      • statusstring
      • subject_didstring
    • created_atstring
    • did_sourcestring
    • display_namestring
    • frameworkobject

      Framework 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
      • namestring
      • packagesobject
        Show properties

        Map of string

    • last_audit_atstring
    • primary_didstring
    • primary_user_display_namestring
    • projectsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProject[]
      Show properties

      Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProject

      • project_urnstring
      • project_uuidstring
      • valid_fromstring
      • valid_untilstring
      • validation_statusstring
    • statusstring
    • throughputinteger[]
    • total_audit_eventsinteger
    • updated_atstring
  • total_countinteger
  • window_endstring
  • window_startstring
Examplejson
{
  "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

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

401Unauthorized

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

403Forbidden

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

404Not Found

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

500Internal Server Error

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}