Skip to main content
GET
/
v1
/
agents
List Agents
curl --request GET \
  --url https://api.truthlocks.com/v1/agents \
  --header 'X-API-Key: <api-key>'
{
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agent_type": "orchestrator",
      "display_name": "<string>",
      "description": "<string>",
      "status": "active",
      "scopes": [
        "<string>"
      ],
      "metadata": {},
      "trust_score": 0.5,
      "public_key": "<string>",
      "session_count": 123,
      "keys": [
        {
          "kid": "<string>",
          "algorithm": "<string>",
          "public_key": "<string>",
          "status": "active"
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123
}

​
List Agents

GET /v1/agents Returns a paginated list of all machine agent identities registered under the authenticated tenant. Results can be filtered by agent type, status, and trust level. Agents are returned in reverse chronological order (newest first).

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Query Parameters

​
agent_type
string
Filter by agent type. One of: "orchestrator", "worker", "inference", "pipeline", "service", "bot", "llm".
​
status
string
Filter by lifecycle status. One of: "active", "suspended", "revoked".
​
trust_level
string
Filter by trust level. One of: "platform_root", "verified_org", "verified_individual", "authenticated", "self_asserted", "anonymous".
​
limit
integer
Maximum number of agents to return per page. Range: 1-200. Default: 50.
​
offset
integer
Number of records to skip for pagination. Default: 0.

​
Response

​
agents
object[]
Array of agent identity objects. Each object contains the full agent record including agent_id, agent_type, display_name, status, trust_level, trust_score, scopes, public_key, key_id, metadata, delegation_depth, created_at, and updated_at.
​
total
integer
Total count of agents matching the filter criteria, across all pages.

​
Example

curl -G https://api.truthlocks.com/v1/agents \
  -H "X-API-Key: tl_live_..." \
  -d "status=active" \
  -d "agent_type=llm" \
  -d "limit=10" \
  -d "offset=0"

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Query Parameters

​
limit
integer
default:25

Maximum number of agents to return

Required range: 1 <= x <= 100
​
offset
integer
default:0

Number of agents to skip

Required range: x >= 0
​
status
enum<string>

Filter by agent status

Available options:
active,
suspended,
revoked
​
agent_type
enum<string>

Filter by agent type

Available options:
orchestrator,
worker,
inference,
pipeline,
service,
bot,
llm

Response

Paginated list of agents

​
items
object[]
​
total
integer