/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. Optional deep_think (VIP/PRO) enables reasoning. 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,
"deep_think": false
}
{
"success": true,
"reply": "Based on the provided architecture diagram, here is the technical breakdown...",
"sender_name": "AI Assistant",
"quota": {
"tier": "vip",
"daily_remaining": 140,
"daily_limit": 150,
"deep_think_available": true,
"deep_think_cost": 2
}
}
/api/chat-quota
Session or API Key
Returns remaining daily turns, Deep Think availability/cost, and premium (PRO v4-pro) remaining. Guests are limited by session plus hashed IP. Logged-in users use account counters.
{
"success": true,
"quota": {
"tier": "free",
"daily_count": 3,
"daily_limit": 20,
"daily_remaining": 17,
"deep_think_available": false,
"deep_think_cost": 0,
"premium_remaining": 0,
"premium_limit": 0,
"allow_image": false,
"max_input_chars": 1000
}
}
/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
}