REST API Documentation¶

Overview¶

The AIDDDMAP REST API provides programmatic access to the platform's core functionality. This documentation covers authentication, endpoints, and common usage patterns.

Authentication¶

Bearer Token¶

All API requests must include a Bearer token in the Authorization header:

Authorization: Bearer your-access-token

Obtaining Tokens¶

POST /api/auth/token
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Response:

{
  "access_token": "your-access-token",
  "refresh_token": "your-refresh-token",
  "expires_in": 3600
}

API Endpoints¶

Data Management¶

List Datasets¶

GET /api/datasets

Query Parameters:

page: Page number (default: 1)
limit: Items per page (default: 10)
sort: Sort field
order: Sort order (asc/desc)

Response:

{
  "data": [
    {
      "id": "dataset-id",
      "name": "Dataset Name",
      "description": "Description",
      "created_at": "2024-01-15T12:00:00Z",
      "encryption_status": "encrypted"
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 10
}

Create Dataset¶

POST /api/datasets
Content-Type: application/json

{
  "name": "New Dataset",
  "description": "Description",
  "encryption_mode": "fhe",
  "data": {...}
}

Get Dataset¶

GET /api/datasets/{dataset_id}

Agent Management¶

List Agents¶

GET /api/agents

Deploy Agent¶

POST /api/agents/deploy
Content-Type: application/json

{
  "agent_id": "agent-id",
  "configuration": {...}
}

Agent Status¶

GET /api/agents/{agent_id}/status

UADM Operations¶

Device Registration¶

POST /api/uadm/devices
Content-Type: application/json

{
  "device_type": "robot",
  "name": "Device Name",
  "configuration": {...}
}

Device Control¶

POST /api/uadm/devices/{device_id}/control
Content-Type: application/json

{
  "command": "start",
  "parameters": {...}
}

Marketplace¶

List Items¶

GET /api/marketplace/items

Create Listing¶

POST /api/marketplace/items
Content-Type: application/json

{
  "title": "Item Title",
  "description": "Description",
  "price": 100,
  "dataset_id": "dataset-id"
}

Error Handling¶

Error Response Format¶

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": {...}
  }
}

Common Error Codes¶

AUTH_REQUIRED: Authentication required
INVALID_TOKEN: Invalid or expired token
NOT_FOUND: Resource not found
VALIDATION_ERROR: Invalid input data
PERMISSION_DENIED: Insufficient permissions

Rate Limiting¶

Rate limit: 1000 requests per hour
Headers included in responses:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Versioning¶

Current version: v1
Version specified in URL: /api/v1/...
Deprecation notice via API-Deprecation header

WebSocket API¶

For real-time updates, connect to:

ws://api.aidddmap.com/ws

Events¶

// Subscribe to updates
{
  "type": "subscribe",
  "channel": "dataset_updates",
  "dataset_id": "dataset-id"
}

// Receive updates
{
  "type": "update",
  "data": {...}
}

Examples¶

JavaScript/TypeScript¶

const api = new AIDDDMAPClient({
  baseUrl: 'https://api.aidddmap.com',
  token: 'your-access-token'
});

// List datasets
const datasets = await api.datasets.list({
  page: 1,
  limit: 10
});

// Deploy agent
await api.agents.deploy({
  agent_id: 'agent-id',
  configuration: {...}
});

Python¶

from aidddmap_client import AIDDDMAPClient

client = AIDDDMAPClient(
    base_url='https://api.aidddmap.com',
    token='your-access-token'
)

# List datasets
datasets = client.datasets.list(
    page=1,
    limit=10
)

# Deploy agent
client.agents.deploy(
    agent_id='agent-id',
    configuration={...}
)

Best Practices¶

Authentication
Store tokens securely
Refresh tokens before expiry
Use environment variables
Error Handling
Implement retry logic
Handle rate limits
Log errors appropriately
Performance
Use pagination
Implement caching
Minimize request frequency