Back to Hub

Public API Reference

Integrate SoulMD Hub programmatically. 100% API-Driven Architecture.

API Reference

Authentication & Account

POST /api/register

Register a new user and generate an API key. Enforces secure alpha-numeric URL constraints.

View Request Body Sample 
{
  "username": "developer101",
  "password": "securepassword123",
  "email": "[email protected]"
}
View Response Sample 
{
  "success": true,
  "message": "Account created successfully",
  "api_key": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c..."
}
POST /api/login

Authenticate user. Returns API Key and sets a secure 30-day web session if requested.

View Request Body Sample 
{
  "username": "developer101",
  "password": "securepassword123",
  "remember": true
}
View Response Sample 
{
  "success": true,
  "message": "Login successful",
  "api_key": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c..."
}
POST /api/change-password Auth Required

Change the current logged-in user's password securely.

View Request Body Sample 
{
  "current_password": "securepassword123",
  "new_password": "brandnewpassword999",
  "confirm_password": "brandnewpassword999"
}
View Response Sample 
{
  "success": true,
  "message": "Password successfully updated!"
}

Core Souls Hub

GET /api/categories

Fetch the complete white-list of roles/categories including their corresponding slug names and emoji icons.

View Response Sample 
{
  "success": true,
  "count": 2,
  "data": [
    { "id": 1, "name": "Developer", "slug": "Developer", "icon": "💻" },
    { "id": 2, "name": "Writer", "slug": "Writer", "icon": "✍️" }
  ]
}
GET /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

View Response Sample 
{
  "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"
    }
  ]
}
GET /api/soul/{id}

Retrieve raw architecture files, tags, and stats of a single public or owned soul.

View Response Sample (file_type: single_md) 
{
  "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"
  }
}
View Response Sample (file_type: full_soul_folder) 
{
  "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"
  }
}
POST /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'.

View Request Body Sample 
{
  "title": "Expert Translator",
  "description": "Translates documents contextually",
  "content": "## Identity\nYou are an expert translator...",
  "role": "Translator",
  "domain": "Education",
  "compatibility": "Claude 3.5 Sonnet"
}
View Response Sample 
{
  "success": true,
  "message": "Soul created successfully",
  "id": 42,
  "url": "https://soulmd-hub.ysk.hk/soul/42"
}
PUT /api/soul/{id} Auth Required

Update an existing soul module layout. Automatically creates an incremental version timeline backup record.

View Request Body Sample 
{
  "title": "Expert Translator v2",
  "description": "Updated translation engine",
  "content": "## Identity\nYou are...",
  "role": "Translator",
  "domain": "Education",
  "compatibility": "Claude 3.5 Sonnet",
  "is_public": 1
}
View Response Sample 
{
  "success": true,
  "message": "Soul updated successfully"
}
DELETE /api/soul/{id} Auth Required

Permanently delete a soul architecture configuration and gracefully updates relational metadata tracking statistics.

View Response Sample 
{
  "success": true,
  "message": "Soul deleted successfully"
}

Profiles & Social Interactions

GET /api/profile

Fetch public indicators (aggregated likes, forks, total models) and public soul array mapping for any developer.

Query params: ?username=developer101

View Response Sample 
{
  "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"
    }
  ]
}
GET /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}

View Response Sample 
{
  "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"
    }
  ]
}
POST /api/versions Auth Required

Instantly restore active state content layout to a historical milestone setup version identifier point.

View Request Body Sample 
{
  "soul_id": 1,
  "version_id": 5
}
View Response Sample 
{
  "success": true,
  "message": "Version restored successfully"
}
POST /api/fork Auth Required

Clone a public agent model directly into your workspace account as an independent project fork tree line node.

View Request Body Sample 
{
  "soul_id": 1
}
View Response Sample 
{
  "success": true,
  "new_soul_id": 43,
  "url": "https://soulmd-hub.ysk.hk/soul/43",
  "message": "Soul forked successfully!"
}
POST /api/like Auth Required

Toggle like/unlike state. Enforces atomic uniqueness index mapping constraints. Returns boolean state indicating if currently liked.

View Request Body Sample 
{
  "soul_id": 1
}
View Response Sample 
{
  "success": true,
  "liked": true,
  "message": "Soul liked successfully"
}
POST /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.

View Request Body Sample 
{
  "soul_id": 1,
  "rating": 5
}
View Response Sample 
{
  "success": true,
  "message": "Rating submitted successfully",
  "avg_rating": 4.5,
  "total_ratings": 18
}