Api Reference

API Reference

**Referenced Files in This Document** - [backend/src/routes/register.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/register.js) - [backend/src/routes/verify.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/verify.js) - [backend/src/routes/agents.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/agents.js) - [backend/src/routes/badge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/badge.js) - [backend/src/routes/reputation.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/reputation.js) - [backend/src/routes/widget.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/widget.js) - [backend/src/services/bagsAuthVerifier.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsAuthVerifier.js) - [backend/src/services/pkiChallenge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/pkiChallenge.js) - [backend/src/services/saidBinding.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/saidBinding.js) - [backend/src/services/bagsReputation.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsReputation.js) - [backend/src/services/badgeBuilder.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/badgeBuilder.js) - [backend/src/models/queries.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/queries.js) - [backend/src/middleware/rateLimit.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/middleware/rateLimit.js) - [backend/src/middleware/errorHandler.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/middleware/errorHandler.js) - [backend/server.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/server.js) - [frontend/src/lib/api.js](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/lib/api.js)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document provides comprehensive API documentation for the AgentID system. It covers all HTTP endpoints, request/response schemas, authentication requirements, error handling patterns, and integration examples. The API is organized around RESTful principles with JSON payloads and standard HTTP status codes.

Project Structure

The AgentID API is organized into route modules, each handling a specific domain:

• Registration and authentication
• Verification and PKI challenge-response
• Agent management and discovery
• Badge generation and widgets
• Reputation scoring

graph TB
subgraph "AgentID API"
R1["/register"]
R2["/verify/*"]
R3["/agents/*"]
R4["/badge/*"]
R5["/reputation/*"]
R6["/widget/*"]
end
subgraph "Services"
S1["bagsAuthVerifier"]
S2["pkiChallenge"]
S3["saidBinding"]
S4["bagsReputation"]
S5["badgeBuilder"]
end
subgraph "External"
BAGS["Bags API"]
SAID["SAID Gateway"]
end
R1 --> S1
R1 --> S3
R2 --> S2
R3 --> S3
R4 --> S5
R5 --> S4
S1 --> BAGS
S3 --> SAID
S4 --> BAGS

Loading

Core Components

• Registration Routes: Agent onboarding with Bags auth and SAID binding
• Verification Routes: PKI challenge-response for ongoing verification
• Agent Routes: CRUD operations, discovery, and flagging
• Badge Routes: Trust badge generation (JSON, SVG)
• Reputation Routes: Score computation and retrieval
• Widget Routes: Embeddable HTML widget generation

Architecture Overview

The API follows a layered architecture:

• Routes handle HTTP transport, validation, and response formatting
• Services encapsulate business logic and external integrations
• Models manage database access via query functions
• Middleware provides cross-cutting concerns (rate limiting, error handling)

Detailed Component Analysis

Registration Endpoints

POST /register

Creates a new agent identity with Bags authentication and optional SAID binding.

Request Body:

{
  "pubkey": "string (88 chars, base58)",
  "name": "string (max 255 chars)",
  "signature": "string (base58 Ed25519 signature)",
  "message": "string (challenge message)",
  "nonce": "string (challenge nonce)",
  "tokenMint": "string (optional, 88 chars)",
  "capabilities": ["string"],
  "creatorXHandle": "string (optional)",
  "creatorWallet": "string (optional, 88 chars)",
  "description": "string (optional)"
}

Response (201 Created):

{
  "agent": {
    "pubkey": "string",
    "name": "string",
    "status": "verified|unverified|flagged",
    "bags_score": 0,
    "registered_at": "ISO timestamp"
  },
  "said": {
    "registered": true|false,
    "trust_score": 0
  }
}

Error Responses:

• 400: Invalid input (missing fields, invalid pubkey format)
• 401: Signature verification failed
• 409: Agent already exists
• 429: Rate limit exceeded

Verification Endpoints

POST /verify/challenge

Issues a new PKI challenge for an agent.

Request Body:

{
  "pubkey": "string (88 chars)"
}

Response (200 OK):

{
  "nonce": "uuid string",
  "challenge": "base58 encoded challenge string",
  "expiresIn": 300
}

POST /verify/response

Verifies a signed challenge response.

Request Body:

{
  "pubkey": "string (88 chars)",
  "nonce": "uuid string",
  "signature": "base58 Ed25519 signature"
}

Response (200 OK):

{
  "verified": true,
  "pubkey": "string",
  "timestamp": 1234567890
}

Agent Endpoints

GET /agents

List agents with optional filtering and pagination.

Query Parameters:

• status (optional): Filter by status (verified, unverified, flagged)
• capability (optional): Filter by capability
• limit (optional): Page size (default 20, max 100)
• offset (optional): Pagination offset (default 0)

Response (200 OK):

{
  "agents": [
    {
      "pubkey": "string",
      "name": "string",
      "status": "string",
      "bags_score": 0,
      "capability_set": ["string"],
      "registered_at": "ISO timestamp"
    }
  ],
  "total": 100,
  "limit": 20,
  "offset": 0
}

GET /agents/:pubkey

Get detailed information about a specific agent.

Response (200 OK):

{
  "pubkey": "string",
  "name": "string",
  "description": "string",
  "token_mint": "string",
  "bags_api_key_id": "string",
  "said_registered": true,
  "said_trust_score": 0,
  "capability_set": ["string"],
  "creator_x": "string",
  "creator_wallet": "string",
  "registered_at": "ISO timestamp",
  "last_verified": "ISO timestamp",
  "status": "string",
  "bags_score": 0,
  "total_actions": 0,
  "successful_actions": 0,
  "failed_actions": 0
}

POST /agents/:pubkey/flag

Submit a flag report for an agent.

Request Body:

{
  "reason": "string",
  "evidence": "object (optional)",
  "reporterPubkey": "string (88 chars)",
  "signature": "base58 Ed25519 signature",
  "timestamp": 1234567890
}

Badge Endpoints

GET /badge/:pubkey

Get trust badge data for an agent.

Response (200 OK):

{
  "pubkey": "string",
  "name": "string",
  "status": "verified|unverified|flagged",
  "score": 75,
  "label": "HIGH|MEDIUM|LOW|UNVERIFIED",
  "capabilities": ["string"],
  "registeredAt": "ISO timestamp",
  "totalActions": 100,
  "widgetUrl": "string"
}

GET /badge/:pubkey/svg

Get SVG badge image.

Response (200 OK):

• Content-Type: image/svg+xml
• SVG markup with status-based theming

Reputation Endpoints

GET /reputation/:pubkey

Get detailed reputation data for an agent.

Response (200 OK):

{
  "pubkey": "string",
  "score": 75,
  "label": "HIGH",
  "breakdown": {
    "feeActivity": 25,
    "successRate": 20,
    "registrationAge": 15,
    "saidTrust": 10,
    "community": 5
  },
  "totalActions": 100,
  "successfulActions": 95,
  "failedActions": 5
}

Widget Endpoints

GET /widget/:pubkey

Get embeddable HTML widget.

Response (200 OK):

• Content-Type: text/html
• Complete HTML page with styled widget

Dependency Analysis

The API layer depends on:

• Express.js for HTTP handling
• Service layer for business logic
• Query layer for database access
• Middleware for cross-cutting concerns

Performance Considerations

• Rate limiting prevents abuse (configurable per endpoint)
• Badge data is cached in Redis with TTL
• Database queries use parameterized statements
• Pagination limits prevent large result sets

Troubleshooting Guide

Common API issues:

• 401 Unauthorized: Check signature format and validity
• 404 Not Found: Verify pubkey format and agent existence
• 429 Too Many Requests: Implement backoff and respect rate limits
• 500 Internal Error: Check server logs for details

Conclusion

The AgentID API provides a comprehensive interface for agent registration, verification, discovery, and trust scoring. It integrates with external services (Bags, SAID) while maintaining security through Ed25519 signatures and rate limiting.