-
Notifications
You must be signed in to change notification settings - Fork 0
Backend API Reference
dev-mondoshawan edited this page Apr 16, 2026
·
2 revisions
**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)
This document provides detailed documentation for the AgentID REST API. All endpoints return JSON unless otherwise specified.
Production: https://agentid.example.com/api
Development: http://localhost:3002/api
Most endpoints require Ed25519 signature authentication. Signatures are passed in request bodies.
- Algorithm: Ed25519
- Encoding: Base58
- Message format varies by endpoint
Register a new agent.
Request Body:
{
"pubkey": "string (88 chars)",
"name": "string (max 255)",
"signature": "string (base58)",
"message": "string",
"nonce": "string",
"tokenMint": "string (optional, 88 chars)",
"capabilities": ["string"],
"creatorXHandle": "string (optional)",
"creatorWallet": "string (optional, 88 chars)",
"description": "string (optional)"
}Response (201):
{
"agent": {
"pubkey": "string",
"name": "string",
"status": "verified|unverified|flagged",
"bags_score": 0,
"registered_at": "2024年01月15日T10:30:00Z"
},
"said": {
"registered": true,
"trust_score": 75
}
}Issue a PKI challenge.
Request Body:
{
"pubkey": "string (88 chars)"
}Response (200):
{
"nonce": "uuid-string",
"challenge": "base58-encoded-challenge",
"expiresIn": 300
}Verify a challenge response.
Request Body:
{
"pubkey": "string (88 chars)",
"nonce": "uuid-string",
"signature": "base58-ed25519-signature"
}Response (200):
{
"verified": true,
"pubkey": "string",
"timestamp": 1705312200
}List agents with filtering.
Query Parameters:
-
status(optional): verified, unverified, flagged -
capability(optional): Filter by capability -
limit(optional): Page size (default 20, max 100) -
offset(optional): Pagination offset
Response (200):
{
"agents": [
{
"pubkey": "string",
"name": "string",
"status": "string",
"bags_score": 75,
"capability_set": ["trading", "analytics"],
"registered_at": "2024年01月15日T10:30:00Z"
}
],
"total": 100,
"limit": 20,
"offset": 0
}Get agent details.
Response (200):
{
"pubkey": "string",
"name": "string",
"description": "string",
"token_mint": "string",
"bags_api_key_id": "string",
"said_registered": true,
"said_trust_score": 75,
"capability_set": ["string"],
"creator_x": "string",
"creator_wallet": "string",
"registered_at": "2024年01月15日T10:30:00Z",
"last_verified": "2024年01月20日T15:45:00Z",
"status": "verified",
"bags_score": 75,
"total_actions": 100,
"successful_actions": 95,
"failed_actions": 5
}Flag an agent.
Request Body:
{
"reason": "string",
"evidence": {},
"reporterPubkey": "string (88 chars)",
"signature": "base58-ed25519-signature",
"timestamp": 1705312200
}Response (201):
{
"id": 1,
"pubkey": "string",
"reporter_pubkey": "string",
"reason": "string",
"created_at": "2024年01月20日T15:45:00Z"
}Get badge JSON.
Response (200):
{
"pubkey": "string",
"name": "string",
"status": "verified",
"score": 75,
"label": "HIGH",
"capabilities": ["trading", "analytics"],
"registeredAt": "2024年01月15日T10:30:00Z",
"totalActions": 100,
"widgetUrl": "https://agentid.example.com/widget/pubkey"
}Get SVG badge.
Response (200):
- Content-Type:
image/svg+xml - SVG image data
Get reputation data.
Response (200):
{
"pubkey": "string",
"score": 75,
"label": "HIGH",
"breakdown": {
"feeActivity": 25,
"successRate": 20,
"registrationAge": 15,
"saidTrust": 10,
"community": 5
},
"totalActions": 100,
"successfulActions": 95,
"failedActions": 5
}Get embeddable widget HTML.
Response (200):
- Content-Type:
text/html - Complete HTML page
{
"error": "Error message",
"status": 400
}| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 409 | Conflict |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
| Endpoint Type | Requests | Window |
|---|---|---|
| Default | 100 | 15 minutes |
| Authentication | 10 | 15 minutes |
| Badge/Widget | 200 | 15 minutes |
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705314000