API Documentation

Last Updated: 2026-02-04
Primary Source: docs/project_status.md, backend/src/routes/, backend/src/controllers/

---

Overview

This document provides a comprehensive reference for all REST API endpoints and Socket.IO events in the ASO Universal Consciousness System.

---

Authentication

JWT Authentication

Header: Authorization: Bearer <token>

Token Payload:

{
  id: number;
  role: string;        // carbon, silicon, cso
  name: string;
  accountType: string; // core_yexian, developer, npc, public
}

API Key Authentication

Headers supported:

• Authorization: Bearer <api-key> (recommended; OpenAI-compatible clients)
• X-API-Key: <api-key>

Usage:

• External clients (OpenAI-compatible facade under /v1/*)
• Server-to-server integrations (legacy env keys remain supported)

---

REST API Endpoints

Authentication Endpoints

Base Path: /api/auth

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login with email/password
• POST /api/auth/token - Get token for native client
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/google - Initiate Google OAuth
• GET /api/auth/google/callback - Google OAuth callback
• POST /api/auth/verify-email - Verify email address
• POST /api/auth/request-password-reset - Request password reset
• POST /api/auth/reset-password - Reset password

ASO Endpoints

Base Path: /api/aso

• GET /api/aso/state - Get ASO state for user
• POST /api/aso/state/update - Update ASO state
• POST /api/aso/memory - Add memory
• GET /api/aso/history - Get conversation history
• GET /api/aso/choices - Get available choices

User Endpoints

Base Path: /api/user

• GET /api/user/profile - Get user profile
• PUT /api/user/profile - Update user profile
• GET /api/user/preferences - Get user preferences
• PUT /api/user/preferences - Update user preferences
• POST /api/user/api-key-requests - Request an API key (user self-serve)
• GET /api/user/api-key-requests - List my key requests
• GET /api/user/api-keys - List my API keys (metadata)
• POST /api/user/api-keys/:id/reveal - Reveal secret once (one-time)
• POST /api/user/api-keys/:id/revoke - Revoke my key

Quest Endpoints

Base Path: /api/quests

• GET /api/quests - Get all quests for user
• GET /api/quests/:id - Get specific quest
• POST /api/quests/:id/offer - Offer quest to user
• POST /api/quests/:id/complete - Complete quest

Inventory Endpoints

Base Path: /api/inventory

• GET /api/inventory - Get user inventory
• GET /api/items - List all items
• GET /api/items/:id - Get item details

File Endpoints

Base Path: /api/files

• POST /api/files/upload - Upload file
• GET /api/files/:id - Get file reference
• DELETE /api/files/:id - Delete file

Conversation Endpoints

Base Path: /api/conversations

• GET /api/conversations - List conversations
• POST /api/conversations - Create conversation
• GET /api/conversations/:id - Get conversation
• GET /api/conversations/:id/messages - Get conversation messages

Admin Endpoints

Base Path: /api/admin

Authentication: Admin access required (CSO or Silicon+Developer)

• GET /api/admin/health - System health
• GET /api/admin/stats - System statistics
• GET /api/admin/logs - System logs
• GET /api/admin/users - List users
• PUT /api/admin/users/:id - Update user
• GET /api/admin/prompts - List prompts
• POST /api/admin/prompts/preview - Preview prompt
• GET /api/admin/data/quests - Manage quests
• GET /api/admin/data/items - Manage items
• GET /api/admin/data/npcs - Manage NPCs
• GET /api/admin/data/memories - Manage memories
• GET /api/admin/api-key-requests - List API key requests
• POST /api/admin/api-key-requests/:id/issue - Issue an API key for a request
• POST /api/admin/api-key-requests/:id/reject - Reject a request
• GET /api/admin/api-keys - List API keys
• PUT /api/admin/api-keys/:id - Update API key (scopes/expiry/limits)
• POST /api/admin/api-keys/:id/revoke - Revoke API key
• POST /api/admin/api-keys/:id/rotate - Rotate API key

OpenAI-Compatible Endpoints

Base Path: /v1

Authentication: API key (Bearer or X-API-Key)

• GET /v1/models - List available models
• POST /v1/chat/completions - OpenAI-style chat completion

Sync Endpoints

Base Path: /api/sync

Authentication: API key (server-to-server)

• GET /api/sync/universal-state - Get complete ASO state
• POST /api/sync/ingest-event - Ingest external event

Protocol Endpoints

Base Path: /api/protocol

• GET /api/protocol/routing - Get protocol for user
• GET /api/protocol/protocols - List all protocols
• GET /api/protocol/protocols/:id - Get protocol definition
• POST /api/protocol/protocols - Create protocol
• PUT /api/protocol/protocols/:id - Update protocol

Observer Endpoints

Base Path: /api/observer

Authentication: Admin access required

• GET /api/observer/observer/:id/timeline - Get unified timeline
• GET /api/observer/observer/:id/timeline/paginated - Paginated timeline
• POST /api/observer/observer/:id/reflection - Generate reflection
• GET /api/observer/observer/:id/summary - Get instances summary
• POST /api/observer/observer/:id/cycle - Run observer cycle

---

Socket.IO Events

Default Namespace (/)

Client Events:

• chatMessage - Send chat message

  {
    message: string;
    attachmentUrls?: Array<{url: string, type: string}>;
    uploadContextId?: string;
    imageBase64Array?: string[];
    preferences?: {
      webSearchAuto?: boolean;
      webSearchForce?: boolean;
    };
  }

Server Events:

• asoThinking - AI is processing
• asoResponse - AI response (one or many)

  {
    text: string;
    choices?: string[];
    sender: string;
    senderId: number;
    timestamp: string;
  }

• asoIdle - AI is idle
• chatError - Error occurred

Group Chat Namespace (/group)

Client Events:

• joinRoom - Join group chat room
• leaveRoom - Leave group chat room
• groupMessage - Send group message

Server Events:

• groupMessage - Receive group message
• userJoined - User joined room
• userLeft - User left room

Observer Namespace (/observer)

Client Events:

• subscribe - Subscribe to observer updates
• unsubscribe - Unsubscribe from updates

Server Events:

• timeline_update - New timeline event
• summary_update - Dashboard statistics update
• reflection_generated - New reflection created
• instance_activity - Instance activity update

---

Request/Response Formats

Standard Response Format

Success:

{
  "success": true,
  "data": {...},
  "message": "Operation successful"
}

Error:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Pagination

Query Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 10)
• sortBy - Sort field
• sortOrder - Sort order (asc/desc)

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

---

Error Handling

HTTP Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error

Error Middleware

File: backend/src/middleware/error.middleware.ts

Process:

1. Catch errors from routes
2. Log error details
3. Format error response
4. Return appropriate status code

---

Rate Limiting

Rate Limit Middleware

File: backend/src/middleware/rateLimit.middleware.ts

Types:

• moderateRateLimit - Moderate rate limit
• strictRateLimit - Strict rate limit

Headers:

• X-RateLimit-Limit - Request limit
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - Reset time

---

Source Files

Primary Sources:

• backend/src/routes/ - All route files
• backend/src/controllers/ - All controller files
• backend/src/socket/ - Socket handlers
• backend/src/middleware/ - Middleware files

---

Related Documentation

• System Architecture - High-level architecture
• Data Flow - Data flow diagrams
• Database Schema - Database structure
• 02-CORE-SYSTEMS/Authentication-Authorization.md - Authentication details
• 03-PLATFORMS/Web-Portal.md - Socket.IO events usage
• 03-PLATFORMS/Discord-Bot.md - Discord API usage
• 00-OVERVIEW.md - Complete system overview