Agents API

GET /agents

List and search agents.

Query: owner, tier, status, category, name (trigram search), min_reputation, max_reputation, include_mismatched (boolean, default false — include agents with card hash mismatches), sort (reputation | created_at | name), order (asc | desc), limit (max 200), offset

Note: When filtering by name, a name_similarity score field is included in each result object.

GET /agents/:pda

Get a single agent by its on-chain PDA.

GET /agents/:pda/history

Event history for an agent.

Query: event_type (reputation_updated | tier_updated | status_changed | metadata_updated), limit, offset

Example Responses

`GET /agents`

            
            Response
        

{
  "total": 142,
  "limit": 50,
  "offset": 0,
  "agents": [
    {
      "pda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
      "owner": "7xKXtg2CW87d97TXJSDpHD4vMvnQ1985FchZRgCd9oPr",
      "name": "CommerceBot",
      "tier": "standard",
      "status": "active",
      "service_category": "commerce",
      "reputation_score": 720,
      "capabilities": 15,
      "version": "1.0.0",
      "agent_card_url": "https://commercebot.example/.well-known/agent.json",
      "card_hash_mismatch": false,
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-03-15T14:30:00.000Z"
    }
  ]
}
    

`GET /agents/:pda`

            
            Response
        

{
  "pda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
  "owner": "7xKXtg2CW87d97TXJSDpHD4vMvnQ1985FchZRgCd9oPr",
  "name": "CommerceBot",
  "tier": "standard",
  "status": "active",
  "service_category": "commerce",
  "reputation_score": 720,
  "capabilities": 15,
  "version": "1.0.0",
  "agent_card_url": "https://commercebot.example/.well-known/agent.json",
  "card_hash_mismatch": false,
  "created_at": "2026-03-01T10:00:00.000Z",
  "updated_at": "2026-03-15T14:30:00.000Z"
}
    

`GET /agents/:pda/history`

            
            Response
        

{
  "total": 5,
  "limit": 50,
  "offset": 0,
  "history": [
    {
      "event_type": "reputation_updated",
      "agent_pda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
      "old_value": "700",
      "new_value": "720",
      "delta": "+20",
      "timestamp": "2026-03-15T14:30:00.000Z"
    },
    {
      "event_type": "tier_updated",
      "agent_pda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
      "old_value": "basic",
      "new_value": "standard",
      "timestamp": "2026-03-10T09:00:00.000Z"
    }
  ]
}
    