/api/register
Register a new user and generate an API key. Enforces secure alpha-numeric URL constraints.
{
"username": "developer101",
"password": "securepassword123",
"email": "[email protected]"
}
{
"success": true,
"message": "Account created successfully",
"api_key": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c..."
}
/api/login
Authenticate user. Returns API Key and sets a secure 30-day web session if requested.
{
"username": "developer101",
"password": "securepassword123",
"remember": true
}
{
"success": true,
"message": "Login successful",
"api_key": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c..."
}
/api/change-password
Auth Required
Change the current logged-in user's password securely.
{
"current_password": "securepassword123",
"new_password": "brandnewpassword999",
"confirm_password": "brandnewpassword999"
}
{
"success": true,
"message": "Password successfully updated!"
}
/api/bind-wallet
Auth Required
Bind a Web3 NEAR wallet to the current session account. Requires a valid Ed25519 cryptographic signature payload to prevent identity spoofing. This action is permanent.
{
"action": "bind",
"wallet": "yanshekki.near",
"public_key": "ed25519:G1...",
"signature": "L/xN...",
"message": "soulmd_auth:1716330000000"
}
{
"success": true,
"message": "Wallet bound successfully!"
}
/api/wallet-login
Authenticate user via Web3 wallet. Requires an Ed25519 cryptographic signature signed by the wallet's local session key. Returns a secure web session if the wallet is bound.
{
"account_id": "yanshekki.near",
"public_key": "ed25519:G1...",
"signature": "L/xN...",
"message": "soulmd_auth:1716330000000"
}
{
"success": true
}
/api/chat
Auth Required
VIP / PRO Only
Headless API access to retrieve conversation history. Includes sender identities for multiplayer rendering. Strict permission controls prevent accessing private sessions.
Query params: ?soul_id=1&session_token=random_token_here
{
"success": true,
"messages": [
{
"role": "user",
"sender_name": "developer101",
"content": "Hello! How can you help me today?"
},
{
"role": "assistant",
"sender_name": "AI Assistant",
"content": "I am an expert assistant. I can help you with coding and reasoning tasks."
}
]
}
/api/my-chats
Auth Required
Retrieve a list of all active chat sessions and compressed memory summaries for the authenticated user.
{
"success": true,
"sessions": [
{
"session_token": "unique_session_id_123",
"soul_id": 1,
"summary": "User asked about architecture layout...",
"last_updated": "2026-05-21 14:00:00"
}
]
}
/api/chat
Auth Required
VIP / PRO Only
Headless API access to interact with the core routing engine. Send messages, optionally attach base64 images (Vision AI), and receive responses. Free tier requests to this endpoint will be strictly rejected with a 403 Forbidden status.
Subscription Policy: Direct API integration requires an active VIP or PRO license. If your subscription period expires, your integration will be automatically disabled until a renewal is processed.
{
"action": "chat",
"soul_id": 1,
"session_token": "unique_session_id_123",
"content": "Can you analyze this architecture diagram?",
"image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
"is_private": false
}
{
"success": true,
"reply": "Based on the provided architecture diagram, here is the technical breakdown...",
"sender_name": "AI Assistant"
}
/api/self-chat
Auth Required
BYOK Active
Headless BYOK proxy endpoint. Uses the user's custom encrypted keys stored in the database. Bypasses platform daily limits but enforces Web3 NFT token-gating.
{
"soul_id": 2,
"session_token": "byok_session_token_xyz",
"content": "Execute high-concurrency trace optimization patterns.",
"image": null,
"is_private": true
}
{
"success": true,
"reply": "Optimizing memory structures using stateless concurrent relays...",
"sender_name": "AI Assistant"
}
/api/chat-sync
Real-time Multiplayer Sync & Presence API. Validates connection heartbeats, tracks active online user counts, and returns incremental delta messages with sender identities.
Query params: ?soul_id=1&session_token=random_token_here&last_id=142
{
"success": true,
"online_count": 2,
"new_messages": [
{
"id": 143,
"role": "user",
"sender_name": "Anonymous #E5A1",
"content": "Is anyone else monitoring this cluster thread?"
}
]
}
/api/apps
List curated form-driven mini apps (or fetch one app schema with ?slug=). Detail includes public souls matching the app theme keywords (title/description only; no prompt content). Optional filters: category, q.
Query params: ?category=destiny&q=name&slug=name-advisor
{
"success": true,
"count": 1,
"data": [
{
"slug": "name-advisor",
"icon": "fa-signature",
"category": "destiny",
"title": "Name Advisor",
"description": "Chinese naming / rename suggestions…",
"badge": "popular",
"field_count": 5,
"search_keywords": "改名 命名 naming"
}
]
}
/api/apps
Session or API Key
Validate mini-app form fields and soul_id (must be a public non-NFT soul matching the app theme keywords). Returns formatted message content for client redirect to /chat/{soul_id}/{session}. Does not call the LLM — chat API applies tier limits and generates the reply.
{
"slug": "name-advisor",
"soul_id": 7303,
"fields": {
"surname": "Chen",
"gender": "female",
"birth_datetime": "1989-09-01 06:00",
"preferences": "gentle, wood/fire",
"count": "3"
}
}
{
"success": true,
"slug": "name-advisor",
"soul_id": 7303,
"content": "Surname: Chen\nGender style: Feminine\n…",
"chat_path": "/chat/7303"
}
/api/categories
Fetch the complete white-list of roles/categories including their corresponding slug names and emoji icons.
{
"success": true,
"count": 2,
"data": [
{ "id": 1, "name": "Developer", "slug": "Developer", "icon": "💻" },
{ "id": 2, "name": "Writer", "slug": "Writer", "icon": "📝" }
]
}
/api/souls
List, search and filter public souls. Optimized with strict DB select limits.
Query params: ?limit=20&offset=0&q=ai&sort=popular&role=Developer
{
"success": true,
"count": 1,
"data": [
{
"id": 1,
"title": "Expert Translator",
"description": "Translates documents contextually",
"role": "Translator",
"domain": "Education",
"compatibility": "Claude 3.5 Sonnet",
"file_type": "single_md",
"like_count": 12,
"fork_count": 3,
"created_at": "2026-05-21 12:00:00"
}
]
}
/api/soul/{id}
Retrieve raw architecture files, tags, and stats of a single public or owned soul.
{
"success": true,
"data": {
"id": 1,
"user_id": 5,
"title": "Expert Translator",
"description": "Translates documents contextually",
"content": "## Identity\nYou are an expert translator...",
"file_type": "single_md",
"role": "Translator",
"domain": "Education",
"compatibility": "Claude 3.5 Sonnet",
"is_public": 1,
"like_count": 12,
"fork_count": 3,
"created_at": "2026-05-21 12:00:00"
}
}
{
"success": true,
"data": {
"id": 2,
"user_id": 5,
"title": "Advanced Dev Architecture",
"description": "Full-stack code assistant package layout",
"content": "{\n \"SOUL.md\": \"## Identity\\nYou are a senior developer...\",\n \"STYLE.md\": \"## Voice\\nConcise, code-heavy...\",\n \"RULES.md\": \"## Hard Rules\\nNever write legacy code...\"\n}",
"file_type": "full_soul_folder",
"role": "Developer",
"domain": "Coding & Dev",
"compatibility": "GPT-4o",
"is_public": 1,
"like_count": 88,
"fork_count": 15,
"created_at": "2026-05-21 14:22:10"
}
}
/api/souls
Auth Required
Publish a brand new AI agent. Automatically detects single .md prompt or full Modular configuration folders.
CRITICAL CONSTRAINT: The role field inside the request body MUST strictly use one of the slug values provided by the /api/categories API. Invalid roles will be forcefully fallbacked to 'Other'.
{
"title": "Expert Translator",
"description": "Translates documents contextually",
"content": "## Identity\nYou are an expert translator...",
"role": "Translator",
"domain": "Education",
"compatibility": "Claude 3.5 Sonnet"
}
{
"success": true,
"message": "Soul created successfully",
"id": 42,
"url": "https://soulmd-hub.ysk.hk/soul/42"
}
/api/soul/{id}
Auth Required
Update an existing soul module layout. Automatically creates an incremental version timeline backup record.
{
"title": "Expert Translator v2",
"description": "Updated translation engine",
"content": "## Identity\nYou are...",
"role": "Translator",
"domain": "Education",
"compatibility": "Claude 3.5 Sonnet",
"is_public": 1
}
{
"success": true,
"message": "Soul updated successfully"
}
/api/soul/{id}
Auth Required
Permanently delete a soul architecture configuration and gracefully updates relational metadata tracking statistics.
{
"success": true,
"message": "Soul deleted successfully"
}
/api/profile
Fetch public indicators (aggregated likes, forks, total models) and public soul array mapping for any developer.
Query params: ?username=developer101
{
"success": true,
"user": {
"username": "developer101",
"joined_at": "2026-05-20 10:00:00"
},
"stats": {
"total_souls": 5,
"total_likes": 24,
"total_forks": 8
},
"souls": [
{
"id": 1,
"title": "Expert Translator",
"description": "Translates documents...",
"role": "Translator",
"domain": "Education",
"compatibility": "Claude 3.5 Sonnet",
"file_type": "single_md",
"like_count": 12,
"fork_count": 3,
"created_at": "2026-05-21 12:00:00"
}
]
}
/api/versions
Retrieve full historical rollback archive versions of a soul. Protected by strict IDOR multi-tenant permission validation check.
Query params: ?soul_id={id}
{
"success": true,
"count": 1,
"data": [
{
"id": 12,
"soul_id": 1,
"title": "Expert Translator v1",
"content": "## Identity\nYou are...",
"edited_at": "2026-05-21 15:30:00"
}
]
}
/api/versions
Auth Required
Instantly restore active state content layout to a historical milestone setup version identifier point.
{
"soul_id": 1,
"version_id": 5
}
{
"success": true,
"message": "Version restored successfully"
}
/api/fork
Auth Required
Clone a public agent model directly into your workspace account as an independent project fork tree line node.
{
"soul_id": 1
}
{
"success": true,
"new_soul_id": 43,
"url": "https://soulmd-hub.ysk.hk/soul/43",
"message": "Soul forked successfully!"
}
/api/like
Auth Required
Toggle like/unlike state. Enforces atomic uniqueness index mapping constraints. Returns boolean state indicating if currently liked.
{
"soul_id": 1
}
{
"success": true,
"liked": true,
"message": "Soul liked successfully"
}
/api/rate
Auth Required
Rate between 1 to 5 stars. Submitting again overrides previous row entry record. Returns updated global live averages for instant interface refresh.
{
"soul_id": 1,
"rating": 5
}
{
"success": true,
"message": "Rating submitted successfully",
"avg_rating": 4.5,
"total_ratings": 18
}