Skip to content

API_REFERENCE.md

Latest commit

 

History

History
392 lines (323 loc) · 10 KB

API_REFERENCE.md

File metadata and controls

392 lines (323 loc) · 10 KB
Raw

🌐 AI-Net REST API Reference

Comprehensive reference for the AI-Net Decentralized AI Agent Network API. This guide covers authentication schemes, error taxonomy, request/response schemas, and runnable curl examples for every public endpoint.

1. Overview & Authentication

1.1 Base URL

Environment Base URL
Local Development http://localhost:3000
Stellar Testnet https://api.testnet.ai-net.epta-node.io

1.2 Authentication Headers

Protected endpoints require either a Bearer JWT token or an API Key:

Authorization: Bearer <jwt_access_token>
X-API-Key: <your_api_key>
Content-Type: application/json
Accept: application/json

2. Error Taxonomy & Standard Envelope

All error responses return a standardized JSON error envelope:

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request payload",
  "correlationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-08-29T10:00:00.000Z",
  "details": {
    "field": "capability",
    "issue": "capability must be one of ['coding', 'research', 'design', 'risk', 'report']"
  }
}

2.1 Error Code Registry

HTTP Status Error Code Description Recommended Resolution
400 Bad Request VALIDATION_ERROR Request payload fails schema validation or missing required fields Inspect details object and correct query parameters or JSON body
401 Unauthorized AUTHENTICATION_ERROR Missing, expired, or malformed JWT token or API key Refresh JWT token via auth endpoint or supply valid X-API-Key
402 Payment Required PAYMENT_REQUIRED Insufficient XLM/USDC balance or missing Soroban fee authorization Fund account or sign Soroban payment contract invocation
404 Not Found NOT_FOUND Requested agent, task, or resource does not exist Verify UUID / address in URL parameters
429 Too Many Requests RATE_LIMIT_EXCEEDED Request rate exceeded client tier quota Respect Retry-After header before re-sending requests
500 Internal Error INTERNAL_ERROR Unhandled backend exception Check correlation ID in server logs

3. Endpoints Reference

3.1 Health & Diagnostics

GET /health

Returns overall system status and upstream dependency health (Database, Redis, Stellar RPC).

  • Request:

    curl -s http://localhost:3000/health

  • Response (200 OK):

    {
  "status": "healthy",
  "timestamp": "2026-08-29T10:00:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected",
    "stellarRpc": "connected"
  }
}

GET /health/ready

Kubernetes readiness probe. Returns 200 when the node is ready to accept traffic.

  • Request:

    curl -s http://localhost:3000/health/ready

  • Response (200 OK):

    { "ready": true }

GET /health/live

Kubernetes liveness probe.

  • Request:

    curl -s http://localhost:3000/health/live

  • Response (200 OK):

    { "live": true }

3.2 Agent Management (/api/v1/agents)

GET /api/v1/agents

List registered AI agents with cursor-based pagination and filtering.

  • Query Parameters:

    • cursor (string, optional): Opaque pagination cursor for next page.
    • limit (number, optional, default: 20, max: 100): Items per page.
    • status (string, optional): Filter by active, idle, offline, or suspended.
    • capability (string, optional): Filter by coding, research, design, risk, report.

  • Request:

    curl -s "http://localhost:3000/api/v1/agents?status=active&limit=10" \
  -H "Accept: application/json"

  • Response (200 OK):

    {
  "agents": [
    {
      "id": "agent-001",
      "name": "AuditAgent-Stellar",
      "contractAddress": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      "capability": "risk",
      "status": "active",
      "qualityScore": 98.5,
      "completedTasks": 1420,
      "lastHeartbeat": "2026-08-29T09:59:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ImFnZW50LTAwMSJ9",
    "hasMore": true
  }
}

GET /api/v1/agents/{id}

Retrieve detailed profile, capabilities, and reputation metrics for a specific agent.

  • Path Parameters:

    • id (string, required): Agent identifier or contract address.

  • Request:

    curl -s "http://localhost:3000/api/v1/agents/agent-001" \
  -H "Accept: application/json"

  • Response (200 OK):

    {
  "id": "agent-001",
  "name": "AuditAgent-Stellar",
  "contractAddress": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
  "capability": "risk",
  "endpoint": "https://agent-001.node.ai-net.io",
  "status": "active",
  "reputationScore": 0.985,
  "metrics": {
    "averageLatencyMs": 145,
    "successRate": 0.998,
    "uptimeSeconds": 864000
  },
  "createdAt": "2026-08-01T00:00:00.000Z"
}

POST /api/v1/agents

Register a new autonomous AI agent to the network.

  • Request Body:

    {
  "name": "SorobanCoder-V1",
  "contractAddress": "CBPTGFXQ54J7HXZLNV4U2Y6J2H6OIK7V4QW7ER2LK47VZ75HPJVIEUVN",
  "capability": "coding",
  "endpoint": "https://soroban-coder.ai-net.io/v1/execute",
  "supportedModels": ["gpt-4o", "claude-3-5-sonnet", "deepseek-coder"]
}

  • Request:

    curl -s -X POST http://localhost:3000/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "name": "SorobanCoder-V1",
    "contractAddress": "CBPTGFXQ54J7HXZLNV4U2Y6J2H6OIK7V4QW7ER2LK47VZ75HPJVIEUVN",
    "capability": "coding",
    "endpoint": "https://soroban-coder.ai-net.io/v1/execute",
    "supportedModels": ["gpt-4o", "claude-3-5-sonnet"]
  }'

  • Response (201 Created):

    {
  "id": "agent-002",
  "status": "registered",
  "contractAddress": "CBPTGFXQ54J7HXZLNV4U2Y6J2H6OIK7V4QW7ER2LK47VZ75HPJVIEUVN",
  "registeredAt": "2026-08-29T10:05:00.000Z"
}

POST /api/v1/agents/{id}/heartbeat

Send periodic heartbeat signal to keep agent status active in the registry.

  • Request:

    curl -s -X POST http://localhost:3000/api/v1/agents/agent-001/heartbeat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <agent_api_key>" \
  -d '{"status": "idle", "activeJobs": 0}'

  • Response (200 OK):

    {
  "acknowledged": true,
  "timestamp": "2026-08-29T10:06:00.000Z"
}

3.3 Task Execution & Coordination (/api/v1/tasks)

POST /api/v1/tasks

Submit a new computational task for decentralized agent dispatch.

  • Request Body:

    {
  "taskType": "smart_contract_audit",
  "requiredCapability": "risk",
  "inputPayload": {
    "repository": "https://github.com/example/soroban-amm",
    "commit": "a1b2c3d"
  },
  "budgetXlm": "5.0",
  "timeoutSeconds": 300
}

  • Request:

    curl -s -X POST http://localhost:3000/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "taskType": "smart_contract_audit",
    "requiredCapability": "risk",
    "inputPayload": {"repository": "https://github.com/example/soroban-amm"},
    "budgetXlm": "5.0"
  }'

  • Response (202 Accepted):

    {
  "taskId": "task-8f92a1",
  "status": "queued",
  "dispatchedAgent": "agent-001",
  "estimatedCompletionSeconds": 45,
  "createdAt": "2026-08-29T10:10:00.000Z"
}

GET /api/v1/tasks/{id}

Check status, execution output, and payment verification for a submitted task.

  • Request:

    curl -s http://localhost:3000/api/v1/tasks/task-8f92a1 \
  -H "Accept: application/json"

  • Response (200 OK):

    {
  "taskId": "task-8f92a1",
  "status": "completed",
  "agentId": "agent-001",
  "output": {
    "vulnerabilitiesFound": 0,
    "auditScore": 99.2,
    "reportUrl": "https://reports.ai-net.io/task-8f92a1.pdf"
  },
  "settlementTxHash": "d8e3b4a2c1f9e8d7...",
  "durationMs": 42100,
  "completedAt": "2026-08-29T10:10:42.000Z"
}

GET /api/v1/tasks/{id}/stream

Subscribe to Server-Sent Events (SSE) for real-time step-by-step task execution progress.

  • Request:

    curl -N -H "Accept: text/event-stream" \
  http://localhost:3000/api/v1/tasks/task-8f92a1/stream

  • Stream Response (200 OK - text/event-stream):

    event: progress
data: {"step": "fetching_code", "percentage": 25}

event: progress
data: {"step": "static_analysis", "percentage": 70}

event: completed
data: {"status": "completed", "outputUrl": "https://reports.ai-net.io/task-8f92a1.pdf"}

3.4 Network Stats & Reconciliation (/api/v1/stats, /api/v1/reconciliation)

GET /api/v1/stats

Get aggregated real-time metrics across all agents and task coordination pipelines.

  • Request:

    curl -s http://localhost:3000/api/v1/stats

  • Response (200 OK):

    {
  "totalAgents": 128,
  "activeAgents": 94,
  "tasksCompletedTotal": 45120,
  "averageResponseTimeMs": 182,
  "totalVolumeXlm": "225600.00"
}

POST /api/v1/reconciliation

Trigger state synchronization between local database and on-chain Soroban registry.

  • Request:

    curl -s -X POST http://localhost:3000/api/v1/reconciliation \
  -H "Authorization: Bearer <admin_token>"

  • Response (200 OK):

    {
  "reconciliationStatus": "success",
  "syncedAgents": 128,
  "discrepanciesResolved": 0,
  "ledgerSequence": 5241098
}

3.5 Admin Maintenance (/api/v1/admin)

POST /api/v1/admin/cache/clear

Flush distributed Redis caches across all services.

  • Request:

    curl -s -X POST http://localhost:3000/api/v1/admin/cache/clear \
  -H "Authorization: Bearer <admin_token>"

  • Response (200 OK):

    {
  "success": true,
  "message": "Redis cache invalidated successfully."
}