Backend API Reference

Backend 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)

Table of Contents

1. Introduction
2. Base URL
3. Authentication
4. Endpoints
5. Error Handling
6. Rate Limiting

Introduction

This document provides detailed documentation for the AgentID REST API. All endpoints return JSON unless otherwise specified.

Base URL

Production: https://agentid.provenanceai.network/api
Development: http://localhost:3002/api

Authentication

Most endpoints require Ed25519 signature authentication. Signatures are passed in request bodies.

Signature Format

• Algorithm: Ed25519
• Encoding: Base58
• Message format varies by endpoint

Endpoints

Registration

POST /register

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-15T10:30:00Z"
  },
  "said": {
    "registered": true,
    "trust_score": 75
  }
}

Verification

POST /verify/challenge

Issue a PKI challenge.

Request Body:

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

Response (200):

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

POST /verify/response

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
}

Agents

GET /agents

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-15T10:30:00Z"
    }
  ],
  "total": 100,
  "limit": 20,
  "offset": 0
}

GET /agents/:pubkey

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-15T10:30:00Z",
  "last_verified": "2024-01-20T15:45:00Z",
  "status": "verified",
  "bags_score": 75,
  "total_actions": 100,
  "successful_actions": 95,
  "failed_actions": 5
}

POST /agents/:pubkey/flag

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-20T15:45:00Z"
}

Badge

GET /badge/:pubkey

Get badge JSON.

Response (200):

{
  "pubkey": "string",
  "name": "string",
  "status": "verified",
  "score": 75,
  "label": "HIGH",
  "capabilities": ["trading", "analytics"],
  "registeredAt": "2024-01-15T10:30:00Z",
  "totalActions": 100,
  "widgetUrl": "https://agentid.provenanceai.network/widget/pubkey"
}

GET /badge/:pubkey/svg

Get SVG badge.

Response (200):

• Content-Type: image/svg+xml
• SVG image data

Reputation

GET /reputation/:pubkey

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
}

Widget

GET /widget/:pubkey

Get embeddable widget HTML.

Response (200):

• Content-Type: text/html
• Complete HTML page

Error Handling

Error Response Format

{
  "error": "Error message",
  "status": 400
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
409	Conflict
429	Too Many Requests
500	Internal Server Error

Rate Limiting

Limits

Endpoint Type	Requests	Window
Default	100	15 minutes
Authentication	10	15 minutes
Badge/Widget	200	15 minutes

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705314000