API Reference¶

Overview¶

The AIDDDMAP API provides a comprehensive set of endpoints for interacting with the platform programmatically. This reference documents all available endpoints, their parameters, and response formats.

Authentication¶

All API requests must include an authentication token in the Authorization header:

Authorization: Bearer <your_token>

Base URL¶

https://api.aidddmap.com/v1

Endpoints¶

Analytics¶

Get Analytics Data¶

POST /api/analytics

Request Body:

{
  userId?: string;
  filters: {
    dateRange: "day" | "week" | "month" | "year";
    dataType: "all" | "marketplace" | "agents" | "datastreams";
    view: "overview" | "detailed";
  }
}

Response:

{
  overview: {
    totalTransactions: number;
    activeAgents: number;
    dataProcessed: number;
    revenue: number;
  };
  marketplace: {
    sales: number[];
    topItems: Array<{ name: string; sales: number }>;
    categories: Record<string, number>;
  };
  agents: {
    performance: number[];
    distribution: Record<string, number>;
    tasks: Array<{ name: string; count: number }>;
  };
  system: {
    health: {
      cpu: number;
      memory: number;
      storage: number;
      network: number;
    };
    alerts: Array<{ type: string; message: string }>;
  };
}

Marketplace¶

List Items¶

GET /api/marketplace/items

Query Parameters:

page (number): Page number for pagination
limit (number): Items per page
category (string): Filter by category
status (string): Filter by status
search (string): Search query

Response:

{
  items: Array<{
    id: string;
    name: string;
    description: string;
    price: number;
    category: string;
    status: string;
    encryption: {
      available: boolean;
      types: string[];
      required: boolean;
    };
    createdAt: string;
    updatedAt: string;
  }>;
  total: number;
  page: number;
  limit: number;
}

Create Item¶

POST /api/marketplace/items

Request Body:

{
  name: string;
  description: string;
  price: number;
  category: string;
  encryption: {
    available: boolean;
    types: string[];
    required: boolean;
  };
}

Update Item¶

PUT /api/marketplace/items/:id

Request Body:

{
  name?: string;
  description?: string;
  price?: number;
  category?: string;
  encryption?: {
    available: boolean;
    types: string[];
    required: boolean;
  };
}

Users¶

List Users¶

GET /api/users

Query Parameters:

page (number): Page number
limit (number): Users per page
role (string): Filter by role
status (string): Filter by status
search (string): Search query

Response:

{
  users: Array<{
    id: string;
    username: string;
    email: string;
    role: string;
    status: string;
    walletAddress?: string;
    lastActive: string;
    datastreams: number;
    agents: number;
    encryptionKeys: number;
  }>;
  total: number;
  page: number;
  limit: number;
}

Manage User¶

POST /api/users/manage

Request Body:

{
  action: "suspend" | "activate" | "update";
  userId: string;
  data?: Record<string, any>;
}

Audit Logs¶

Get Audit Logs¶

POST /api/audit-logs

Request Body:

{
  filters: {
    component: string;
    status: string;
    dateRange: string;
    user: string;
  };
  searchQuery: string;
  page: number;
  limit: number;
}

Response:

{
  logs: Array<{
    id: string;
    timestamp: string;
    action: string;
    component: string;
    user: {
      id: string;
      name: string;
      role: string;
    };
    details: string;
    status: "success" | "warning" | "error";
    metadata?: Record<string, any>;
  }>;
  total: number;
  page: number;
  limit: number;
}

System Settings¶

Get Settings¶

GET /api/settings

Response:

{
  encryption: {
    defaultType: "FHE" | "AES" | "ZK";
    minKeyLength: number;
    autoRotateKeys: boolean;
    rotationPeriod: number;
  };
  database: {
    maxConnections: number;
    timeout: number;
    backupEnabled: boolean;
    backupInterval: number;
  };
  network: {
    maxBandwidth: number;
    requestTimeout: number;
    maxConcurrentConnections: number;
  };
  wallet: {
    network: string;
    gasLimit: number;
    autoApproveThreshold: number;
  };
}

Update Settings¶

PUT /api/settings

Request Body:

{
  encryption?: {
    defaultType?: "FHE" | "AES" | "ZK";
    minKeyLength?: number;
    autoRotateKeys?: boolean;
    rotationPeriod?: number;
  };
  database?: {
    maxConnections?: number;
    timeout?: number;
    backupEnabled?: boolean;
    backupInterval?: number;
  };
  network?: {
    maxBandwidth?: number;
    requestTimeout?: number;
    maxConcurrentConnections?: number;
  };
  wallet?: {
    network?: string;
    gasLimit?: number;
    autoApproveThreshold?: number;
  };
}

Error Handling¶

All API endpoints follow a consistent error response format:

{
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
  }
}

Common error codes:

AUTH_ERROR: Authentication failed
INVALID_REQUEST: Invalid request parameters
NOT_FOUND: Resource not found
PERMISSION_DENIED: Insufficient permissions
RATE_LIMITED: Too many requests
SERVER_ERROR: Internal server error

Rate Limiting¶

API requests are rate-limited based on the following tiers:

Basic: 100 requests/minute
Pro: 1000 requests/minute
Enterprise: Custom limits

Rate limit headers are included in all responses:

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

Pagination¶

List endpoints support pagination using the following parameters:

page: Page number (default: 1)
limit: Items per page (default: 20, max: 100)

Response includes pagination metadata:

{
  data: T[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  }
}

Websocket API¶

Real-time updates are available through WebSocket connections:

const ws = new WebSocket('wss://api.aidddmap.com/v1/ws');

// Subscribe to updates
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: ['analytics', 'alerts', 'system-health']
}));

// Handle messages
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Available channels:

analytics: Real-time analytics updates
alerts: System alerts and notifications
system-health: System health metrics
marketplace: Marketplace activity
audit-logs: Real-time audit events

SDK¶

Official SDKs are available for:

JavaScript/TypeScript
Python
Go
Java

Example using the TypeScript SDK:

import { AIDDDMAP } from '@aidddmap/sdk';

const client = new AIDDDMAP({
  apiKey: 'your_api_key',
  environment: 'production'
});

// Get analytics data
const analytics = await client.analytics.get({
  dateRange: 'week',
  dataType: 'all'
});

// Manage marketplace items
const items = await client.marketplace.listItems({
  category: 'agents',
  status: 'active'
});

// Subscribe to real-time updates
client.realtime.subscribe(['analytics', 'alerts'], (data) => {
  console.log('Update received:', data);
});

Best Practices¶

Rate Limiting
Implement exponential backoff for retries
Cache responses when appropriate
Use bulk operations when possible
Error Handling
Always check error responses
Implement proper logging
Handle rate limits gracefully
Security
Store API keys securely
Use HTTPS for all requests
Implement proper token rotation
Performance
Use compression when available
Implement request batching
Optimize payload size

Support¶

For API support and questions:

Email: api-support@aidddmap.com
Documentation: https://docs.aidddmap.com
Status: https://status.aidddmap.com

# Command example
curl -H "Authorization: Bearer token" https://api.example.com

{
  "status": "success",
  "data": {}
}