Developer ReferenceREST API Reference

REST API Reference

The StudioBrain backend exposes a RESTful API on port 8201. All endpoints use JSON request/response bodies and are prefixed with /api/ unless otherwise noted.

Interactive API documentation is available at /docs (Swagger UI) and /redoc (ReDoc) when the backend is running.

Authentication

Most endpoints require a JWT bearer token or session cookie.

Header-based auth:

Authorization: Bearer {jwt_token}

Cookie-based auth (web sessions):

The web auth endpoints set httpOnly cookies automatically. Subsequent requests from the browser include the cookie without explicit header configuration.

Obtaining a token:

POST /api/auth/web/login
Content-Type: application/json
 
{
  "email": "user@example.com",
  "password": "secretpassword"
}

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "tenant_id": "abc123",
  "user_id": "user456",
  "role": "admin"
}

Common Response Patterns

Success (list)

{
  "total": 42,
  "offset": 0,
  "limit": 50,
  "entities": [...]
}

Success (single entity)

{
  "entity_type": "character",
  "entity_id": "rex_marshall",
  "name": "Rex Marshall",
  "status": "active",
  "fields": { ... },
  "markdown_body": "...",
  "primary_asset": "/Characters/rex_marshall/images/portrait.png",
  "validation_errors": [],
  "is_valid": true
}

Error

{
  "detail": "Entity not found: character/unknown_id"
}

Common HTTP status codes:

CodeMeaning
200Success
201Created
400Bad request (validation error, malformed input)
401Unauthorized (missing or invalid token)
403Forbidden (insufficient permissions or feature gate)
404Not found
409Conflict (entity already exists, sync conflict)
422Unprocessable entity (Pydantic validation failure)
429Rate limited
500Internal server error

Entities

Unified entity CRUD for all 16 entity types. The {type} path parameter accepts: character, location, district, brand, faction, item, job, quest, campaign, event, dialogue, timeline, assembly, style_bible, universe.

Prefix: /api/entity

MethodPathDescriptionAuth
GET/{type}/schemaGet template schema for entity typeNo
GET/{type}List entities with filtering and paginationYes
GET/{type}/{id}Get single entity by IDYes
POST/{type}Create new entityYes
PUT/{type}/{id}Update entity fields and/or markdown bodyYes
DELETE/{type}/{id}Soft-delete entity (moves to recycle bin)Yes
POST/{type}/smart-mergeAI-assisted merge of two entity versionsYes
POST/{type}/compareDiff two entity versionsYes
POST/{type}/importImport entity from raw markdown contentYes

Query Parameters (list endpoint)

ParamTypeDefaultDescription
offsetint0Pagination offset
limitint50Maximum results (max 200)
searchstring—Full-text search across name and fields
statusstring—Filter by status (active, archived, draft)
sort_bystringupdated_atSort field
sort_orderstringdescasc or desc

Create Entity

POST /api/entity/character
Content-Type: application/json
Authorization: Bearer {token}
 
{
  "entity_id": "rex_marshall",
  "name": "Rex Marshall",
  "status": "active",
  "fields": {
    "age": "34",
    "gender": "male",
    "faction": "independent",
    "personality_traits": ["resourceful", "paranoid"]
  },
  "markdown_body": "# Rex Marshall\n\n## Background\n\nA former mechanic..."
}

Update Entity

PUT /api/entity/character/rex_marshall
Content-Type: application/json
Authorization: Bearer {token}
 
{
  "fields": {
    "age": "35",
    "personality_traits": ["resourceful", "paranoid", "loyal"]
  }
}

Only the provided fields are updated. Omitted fields are unchanged.

Auth and Users

Prefix: /api

Web Auth (cookie-based)

MethodPathDescriptionAuth
POST/auth/web/loginLogin with email/password, sets httpOnly cookieNo
POST/auth/web/google-ssoLogin via Google SSO tokenNo
GET/auth/web/sessionGet current session info from cookieCookie
POST/auth/web/select-tenantSwitch active tenantCookie

User Management

MethodPathDescriptionAuth
POST/auth/registerRegister new userNo
POST/auth/loginLogin (returns JWT)No
POST/auth/refreshRefresh JWT tokenYes
POST/auth/logoutLogout / revoke tokenYes
GET/auth/meGet current user profileYes
POST/auth/set-passwordSet new passwordYes
POST/auth/forgot-passwordRequest password reset emailNo
POST/auth/reset-passwordReset password with tokenNo
POST/auth/create-inviteCreate user invitation linkYes (admin)
GET/auth/validate-invite/{token}Validate invite tokenNo
POST/auth/register-with-inviteRegister using invite tokenNo

OAuth

MethodPathDescriptionAuth
GET/auth/oauth/providersList configured OAuth providersNo
GET/auth/oauth/googleInitiate Google OAuth flowNo
GET/auth/oauth/google/callbackGoogle OAuth callbackNo
GET/auth/oauth/microsoftInitiate Microsoft OAuth flowNo
GET/auth/oauth/microsoft/callbackMicrosoft OAuth callbackNo
GET/auth/oauth/google/driveInitiate Google Drive OAuthYes
GET/auth/oauth/google/drive/callbackGoogle Drive OAuth callbackYes

Teams and Users (Admin)

MethodPathDescriptionAuth
GET/usersList all usersYes (admin)
GET/users/currentGet current userYes
GET/users/{id}Get user by IDYes (admin)
PUT/users/{id}Update userYes (admin)
DELETE/users/{id}Delete userYes (admin)
PUT/users/{id}/passwordChange user passwordYes (admin)
GET/users/{id}/api-keyGet user AI API keyYes
POST/users/{id}/api-key/regenerateRegenerate AI API keyYes
GET/users/{id}/subscriptionGet user subscriptionYes
PUT/users/{id}/subscriptionUpdate subscription tierYes (admin)
POST/users/{id}/inviteSend user inviteYes (admin)
POST/teamsCreate teamYes
GET/teamsList teamsYes
GET/teams/{id}Get team detailsYes
POST/api-keysCreate API keyYes
GET/api-keysList API keysYes
POST/permission-templatesCreate permission templateYes (admin)
GET/permission-templatesList permission templatesYes

Tenants

MethodPathDescriptionAuth
POST/tenantsCreate tenantYes (admin)
GET/tenants/meGet current tenantYes
PUT/tenants/meUpdate current tenantYes

Registration

MethodPathDescriptionAuth
POST/registerRegister new tenant + userNo
POST/register/with-inviteRegister with beta invite codeNo

Sync and File Operations

Markdown Sync

Prefix: /api

MethodPathDescriptionAuth
GET/sync/statusGet sync status (running, last result)No
GET/sync/check-changesCheck for pending file changesYes
POST/sync/import-changesImport detected file changesYes
POST/sync/save-to-markdown/{type}/{id}Write entity to markdown fileYes
POST/sync/from-markdown/{type}/{id}Read entity from markdown file into DBYes
POST/sync/refresh-allFull re-sync all markdown to DBYes
GET/sync/file-watcher/statusHybrid file watcher statusNo

Entity Sync (bulk)

MethodPathDescriptionAuth
POST/api/entity/sync/allSync all entity types from markdownYes
POST/api/entity/sync/{type}Sync specific entity typeYes
POST/api/entity/validate/allValidate all entitiesYes

Markdown Operations

MethodPathDescriptionAuth
POST/markdown/validate-frontmatterValidate YAML frontmatterYes
POST/markdown/sync-from-filesSync from filesystemYes
POST/markdown/export/{type}/{id}Export entity as markdownYes

Import

MethodPathDescriptionAuth
POST/import/previewPreview markdown import without savingYes
POST/import/smartSmart import with AI-assisted field mappingYes
POST/markdown/formatFormat/normalize markdown contentYes
POST/validation/fixAuto-fix common validation issuesYes
POST/rename-entityRename entity (updates ID, files, references)Yes

Cloud Sync

App-level Cloud Sync

Prefix: /api/cloud-sync

MethodPathDescriptionAuth
POST/pushPush local changes to cloud (PostgreSQL RLS)Yes
GET/pullPull cloud changes to localYes
GET/statusCloud sync statusYes

Desktop Cloud Sync

Prefix: /api/desktop/sync

MethodPathDescriptionAuth
POST/pushPush from desktop to cloudYes
GET/pullPull from cloud to desktopYes
GET/presenceGet online presence infoYes

Conflicts

Prefix: /api/conflicts

MethodPathDescriptionAuth
GET“List unresolved sync conflictsYes
POST/{conflict_id}/resolveResolve a conflict (pick winner)Yes

Google Drive

Drive Storage

Prefix: /api/drive/oauth

MethodPathDescriptionAuth
GET/statusDrive connection statusYes
GET/foldersList Drive folders for pickerYes
POST/select-folderSet project folderYes
POST/disconnectDisconnect Drive storageYes
POST/testTest Drive connectionYes

Drive Files

Prefix: /api/drive

MethodPathDescriptionAuth
GET/statusDrive connection statusYes
GET/filesList Drive filesYes
GET/files/{file_id}Get file metadataYes
GET/files/{file_id}/downloadDownload file contentYes
POST/export-entityExport entity as Google DocYes
PUT/files/{file_id}Update Drive file contentYes
POST/files/{file_id}/shareShare file with another userYes

Drive Webhooks

Prefix: /api/drive/webhook

MethodPathDescriptionAuth
POST“Receive Drive change notificationsNo (webhook)
POST/registerRegister push notification channelYes
DELETE/unregisterStop watching for changesYes
GET/statusWebhook registration statusYes

Drive Cloud Sync

Prefix: /api/drive

MethodPathDescriptionAuth
GET/cloud-sync-statusCloud Drive sync worker statusYes
POST/force-syncForce immediate Drive syncYes

Billing

Prefix: /api/billing

MethodPathDescriptionAuth
GET/pricesList available subscription pricesNo
GET/subscriptionGet current subscription detailsYes
GET/usageGet current BrainBits usageYes
POST/checkoutCreate Stripe checkout sessionYes
POST/portalCreate Stripe customer portal sessionYes
GET/portalRedirect to Stripe customer portalYes
POST/webhookStripe webhook receiverNo (webhook)
GET/statusBilling system statusYes
GET/invoicesList invoicesYes
PUT/quotaUpdate team quota allocationYes (admin)
POST/consume-tokensConsume BrainBits tokensYes
GET/team/membersList team members with billing infoYes
PUT/team/user-quotaUpdate per-user quotaYes (admin)
GET/usage-historyUsage history over timeYes
GET/token-blocksList available token block purchasesYes
POST/purchase-tokensPurchase additional BrainBitsYes
GET/purchase-historyToken purchase historyYes
GET/brainbitsGet BrainBits balanceYes
POST/brainbits/consumeConsume BrainBitsYes

Beta Program

Prefix: /api/beta

MethodPathDescriptionAuth
POST/inviteCreate beta invite codeYes (admin)
GET/validate/{code}Validate invite codeNo
POST/redeemRedeem invite codeYes
POST/invite/revokeRevoke an invite codeYes (admin)
POST/extendExtend beta periodYes (admin)
GET/statsBeta program statisticsYes (admin)
POST/feedbackSubmit beta feedbackYes
GET/feedbackList feedback submissionsYes (admin)
PATCH/feedback/{id}Update feedback statusYes (admin)
POST/waitlistJoin waitlistNo
GET/waitlistList waitlist entriesYes (admin)
POST/waitlist/promotePromote waitlist entry to inviteYes (admin)

Desktop

Prefix: /api/desktop

MethodPathDescriptionAuth
GET/projectsList local projectsNo
POST/projectsCreate new projectNo
DELETE/projects/{name}Delete projectNo
POST/projects/{name}/activateActivate projectNo
POST/projects/{name}/scanScan project for entitiesNo
GET/watcher/statusFile watcher statusNo
POST/watcher/startStart file watcherNo
POST/watcher/stopStop file watcherNo
GET/sync/statusDesktop sync statusNo
GET/sync/queueView sync queueNo
POST/sync/startStart sync workerNo
POST/sync/stopStop sync workerNo
POST/sync/nowTrigger immediate syncNo
POST/sync/force-pushForce push to cloudNo
POST/sync/force-pullForce pull from cloudNo
GET/sync/conflictsList sync conflictsNo
POST/sync/conflicts/{id}/resolveResolve conflictNo
POST/ai/chatDesktop AI chat (offline-capable)No
GET/ai/providersList available AI providersNo
POST/auth/loginDesktop auth loginNo
POST/auth/callbackDesktop auth callbackNo
POST/auth/logoutDesktop auth logoutNo
GET/auth/statusDesktop auth statusNo
POST/ws/connectConnect desktop WebSocketNo
POST/ws/disconnectDisconnect desktop WebSocketNo

Templates and Rules

Templates

Prefix: /api

MethodPathDescriptionAuth
GET/templatesList all templatesNo
GET/templates/entity-typesList available entity typesNo
POST/templates/reloadReload templates from diskYes
GET/templates/{name}Get template contentNo
PUT/templates/{name}Update templateYes
GET/templates/{name}/instructionsGet AI generation instructionsNo
PUT/templates/{name}/instructionsUpdate AI instructionsYes

Rules

Prefix: /api

MethodPathDescriptionAuth
GET/rulesList all rule filesNo
POST/rules/reloadReload rules from diskYes
GET/rules/indexGet rules indexNo
GET/rules/settingsGet rules settingsNo
PUT/rules/settingsUpdate rules settingsYes
POST/rules/validate/{type}Validate entity against rulesYes
GET/rules/{type}Get parsed rules for entity typeNo
GET/rules/{type}/markdownGet raw rule markdownNo
PUT/rules/{type}/markdownUpdate rule markdownYes
PUT/rules/{type}/system-promptUpdate AI system promptYes
POST/rules/{type}Add new ruleYes
PUT/rules/{type}/{rule_id}Update specific ruleYes
DELETE/rules/{type}/{rule_id}Delete specific ruleYes

Schemas

Prefix: /api

MethodPathDescriptionAuth
GET/schemasList all entity schemasNo
GET/schemas/{type}Get schema for entity typeNo

Assets

Prefix: /api

MethodPathDescriptionAuth
GET/assetsList assets with filteringYes
GET/assets/testAsset system testNo
GET/assets/linkedList assets linked to entitiesYes
GET/assets/uploadersList available upload providersYes
GET/assets/{id}Get asset by IDYes
POST/assetsCreate asset recordYes
PUT/assets/{id}Update asset metadataYes
DELETE/assets/{id}Delete assetYes
POST/assets/scanScan all entity folders for new assetsYes
POST/assets/scan/{type}/{id}Scan specific entity for assetsYes
POST/assets/sanitize-idsFix invalid asset IDsYes
POST/assets/uploadUpload asset fileYes
POST/assets/auto-tagAI auto-tag assetYes
POST/assets/thumbnailGenerate thumbnailYes
POST/assets/ai-rescanRe-analyze asset with AIYes
GET/assets/by-brand/{brand_id}Get assets for brandYes
GET/assets/duplicatesFind duplicate assetsYes
PUT/assets/{id}/statusUpdate asset statusYes
POST/assets/{id}/relationshipsAdd asset relationshipYes
GET/assets/{id}/relationshipsGet asset relationshipsYes
GET/assets/stats/overviewAsset statisticsYes

Asset Queue

MethodPathDescriptionAuth
GET/asset-queue/statusQueue processing statusYes
POST/asset-queue/pausePause queue processingYes
POST/asset-queue/resumeResume queue processingYes
GET/asset-queue/asset/{id}Get asset queue entryYes
POST/asset-queue/vram-pressureReport VRAM pressureYes
POST/asset-queue/rescan/{id}Re-queue asset for analysisYes
POST/asset-queue/batch-rescanBatch re-queue assetsYes

File Serving

MethodPathDescriptionAuth
GET/files/{path}Serve static fileNo
POST/upload/character/{id}/imageUpload character imageYes
POST/upload/location/{id}/imageUpload location imageYes
POST/upload/brand/{id}/imageUpload brand imageYes
POST/upload/{type}/{id}Upload file for any entityYes

Plugins

Plugin Management

Prefix: /api/plugins

MethodPathDescriptionAuth
GET“List all pluginsYes
POST/installInstall plugin from URL/archiveYes (admin)
POST/{id}/enableEnable pluginYes (admin)
POST/{id}/disableDisable pluginYes (admin)
POST/{id}/updateUpdate pluginYes (admin)
DELETE/{id}Uninstall pluginYes (admin)
POST/{id}/backupBackup plugin dataYes (admin)
POST/{id}/restoreRestore plugin from backupYes (admin)
GET/{id}/backupsList plugin backupsYes
GET/{id}/settingsGet plugin settingsYes
PUT/{id}/settingsUpdate plugin settingsYes (admin)
GET/{id}/settings/userGet user-specific settingsYes
PUT/{id}/settings/userUpdate user-specific settingsYes
GET/page/{id}Serve plugin pageYes
GET/page/{id}/{subpath}Serve plugin subpageYes
GET/panel/{id}/{panel_id}Serve plugin panel HTMLYes

Plugin Data

Prefix: /api/plugins

MethodPathDescriptionAuth
GET/{id}/data/{record_type}List plugin data recordsYes
POST/{id}/data/{record_type}Create data recordYes
GET/{id}/data/{record_type}/{record_id}Get data recordYes
PUT/{id}/data/{record_type}/{record_id}Update data recordYes
DELETE/{id}/data/{record_type}/{record_id}Delete data recordYes

Plugin Marketplace

Prefix: /api/marketplace

MethodPathDescriptionAuth
GET“Browse marketplaceNo
GET/infoMarketplace infoNo
GET/{id}Get plugin detailsNo
POST/registryRegister plugin in marketplaceYes (admin)
GET/tenant/installedList tenant’s installed pluginsYes
POST/tenant/installInstall from marketplaceYes
POST/tenant/{id}/enableEnable installed pluginYes
POST/tenant/{id}/disableDisable installed pluginYes
DELETE/tenant/{id}Uninstall marketplace pluginYes

Search and Relationships

Prefix: /api

MethodPathDescriptionAuth
GET/searchSearch across entity typesYes
GET/search/allFull-text search all entitiesYes
GET/recentRecently updated entitiesYes
GET/relationships/{type}/{id}Get entity relationshipsYes
GET/graph/universeGet full entity relationship graphYes
GET/graph/entity/{type}/{id}Get entity-centric subgraphYes

Cross-References and Context

Prefix: /api/entity

MethodPathDescriptionAuth
POST/cross-reference/queryQuery cross-referencesYes
POST/cross-reference/contextBuild cross-reference contextYes
POST/cross-reference/romanceFind romantic connectionsYes
POST/cross-reference/faction-warFind faction conflictsYes
GET/cross-reference/validate/{type}/{id}Validate referencesYes
POST/hybrid-relationshipsDiscover hybrid relationshipsYes
POST/semantic-connectionsFind semantic connections via embeddingsYes
POST/structured-relationshipsStructured relationship queryYes
POST/enhanced-contextBuild enhanced entity context for AIYes

Layouts

Prefix: /api/layouts

MethodPathDescriptionAuth
GET“List all layout definitionsNo
GET/{type}Get layout for entity typeNo
PUT/{type}Update layout for entity typeYes
POST/{type}/resetReset layout to defaultsYes
DELETE/{type}Delete custom layoutYes

Timeline

Prefix: /api/timeline

MethodPathDescriptionAuth
GET“List timeline events with filteringYes
POST/auto-populateAuto-populate timeline from entity dataYes
GET/conflictsFind timeline conflictsYes
POST/exportExport timeline dataYes

Assembly System

Prefix: /api/assembly

MethodPathDescriptionAuth
GET/{id}/slotsList assembly slotsYes
GET/{id}/slots/{group}Get slots by groupYes
POST/{id}/slotsAdd slot to assemblyYes
DELETE/{id}/slots/{group}/{name}Remove slotYes
PUT/{id}/slots/reorderReorder slotsYes
PUT/{id}/slots/{group}/{name}/transformTransform slotYes
POST/{id}/parentSet parent assemblyYes
DELETE/{id}/parentRemove parentYes
GET/{id}/inheritanceGet inheritance chainYes
POST/{id}/slots/lockLock slotsYes
POST/{id}/slots/unlockUnlock slotsYes
GET/{id}/zombie/{stage}Get zombie stage dataYes
POST/{id}/zombie/validateValidate zombie assemblyYes
GET/export/profilesList export profilesYes
POST/{id}/export/{profile}Export assemblyYes
GET/{id}/manifest/{profile}Get export manifestYes
POST/{id}/validateValidate assemblyYes
GET/{id}/validate/statusValidation statusYes
GET/{id}/completenessCheck assembly completenessYes
GET/{id}/previewPreview assemblyYes
GET/by-asset/{asset_id}Find assemblies using assetYes
POST/auto-detect-slotAuto-detect slot type for assetYes
GET/template/typesList assembly template typesYes
GET/template/slot-definitionsGet slot definitionsYes
POST/export/profiles/reloadReload export profilesYes

Recycle Bin

Prefix: /api

Entities

MethodPathDescriptionAuth
GET/recycle-bin/entityList recycled entitiesYes
POST/recycle-bin/entity/{type}/{id}/restoreRestore entityYes
DELETE/recycle-bin/entity/{type}/{id}/permanentPermanently deleteYes (admin)
POST/recycle-bin/entity/emptyEmpty entity recycle binYes (admin)

Assets

MethodPathDescriptionAuth
GET/recycle-binList recycled assetsYes
POST/recycle-bin/{id}/restoreRestore assetYes
DELETE/recycle-bin/{id}/permanentPermanently delete assetYes (admin)
POST/recycle-bin/emptyEmpty asset recycle binYes (admin)
POST/recycle-bin/auto-cleanupAuto-cleanup old itemsYes (admin)

Services and Health

MethodPathDescriptionAuth
GET/healthBasic health checkNo
GET/api/healthBasic health check (prefixed)No
GET/health/detailedDetailed health with DB statusNo
GET/api/check-entity-id/{id}Check if entity ID is availableNo
GET/api/services/statusService status (backend, AI, DB)Yes
POST/api/services/restart/{service}Restart a serviceYes (admin)
POST/api/services/terminate/aiTerminate AI serviceYes (admin)
GET/api/services/logs/{service}Get service logsYes
POST/api/services/logs/{service}/clearClear service logsYes (admin)
GET/api/services/logs/listList available log filesYes
POST/api/logs/frontendSubmit frontend log entriesNo

WebSocket

Endpoint: ws://host:8201/api/ws

Connect with a JWT token as a query parameter or in the first message. The WebSocket channel provides real-time events:

EventDescription
entity_updatedEntity was created, updated, or deleted
sync_completedMarkdown sync finished
presence_updateUser came online/offline/started editing
brainbits_deductedBrainBits consumed for AI operation
asset_processedAsset analysis completed

Presence

MethodPathDescriptionAuth
GET/api/presence/{tenant_id}Get online users for tenantYes
GET/api/presence/{tenant_id}/editingGet who is editing whatYes

Settings

Prefix: /api/settings

MethodPathDescriptionAuth
GET“Get user settingsYes
PUT“Update user settingsYes
GET/keysList configured AI provider keysYes
PUT/keys/{provider}Set AI provider keyYes
DELETE/keys/{provider}Remove AI provider keyYes

Feature Gates

Prefix: /api/features

MethodPathDescriptionAuth
GET“Get enabled features for current tierYes
GET/tiersList all tiers and their featuresNo

Groups and Quotas

Groups

Prefix: /api/groups

MethodPathDescriptionAuth
GET/presetsList group presetsYes
GET/user/{user_id}Get user’s groupsYes
POST“Create groupYes (admin)
GET“List groupsYes
GET/{id}Get groupYes
PUT/{id}Update groupYes (admin)
DELETE/{id}Delete groupYes (admin)
POST/{id}/membersAdd member to groupYes (admin)
DELETE/{id}/members/{user_id}Remove memberYes (admin)

Quota Groups

Prefix: /api/quota-groups

MethodPathDescriptionAuth
GET/List quota groupsYes
PUT/{id}/quotaUpdate group quotaYes (admin)
GET/{id}/usageGet group usageYes
POST/{id}/resetReset group usage countersYes (admin)

Sharing

Prefix: (none, uses full paths)

MethodPathDescriptionAuth
POST/api/sharesCreate share linkYes
GET/api/sharesList sharesYes
DELETE/api/shares/{id}Delete shareYes
GET/api/share/{code}Access shared contentNo
GET/api/share/{code}/entities/{type}List entities in shareNo

Database Admin

Prefix: /api

MethodPathDescriptionAuth
GET/database/testTest database connectionYes
GET/database/tablesList database tablesYes (admin)
GET/database/tables/{name}/dataView table dataYes (admin)
POST/database/queryExecute read-only SQL queryYes (admin)
GET/database/statisticsDatabase statisticsYes
GET/database/entitiesEntity count by typeYes
POST/database/exportExport databaseYes (admin)
POST/database/importImport databaseYes (admin)
POST/database/backupCreate database backupYes (admin)

AI (Backend-Proxied)

These backend endpoints proxy specific AI operations. Most AI operations go directly to the AI service on port 8202.

Prefix: /api

MethodPathDescriptionAuth
GET/image/styles/{type}Get image generation styles for entity typeYes
POST/generate/characterGenerate character via AIYes
POST/enhance/character/{id}Enhance existing characterYes
POST/generate/dialogue/{id}Generate dialogue for characterYes

Image Presets

Prefix: /api

MethodPathDescriptionAuth
GET/presetsList image generation presetsYes
POST/presetsCreate presetYes
GET/presets/{id}Get presetYes
PUT/presets/{id}Update presetYes
DELETE/presets/{id}Delete presetYes

Context Profiles

Prefix: /api/context-profiles

MethodPathDescriptionAuth
GET“List context profilesYes
POST“Create context profileYes
GET/{id}Get context profileYes
PUT/{id}Update context profileYes
DELETE/{id}Delete context profileYes
POST/{id}/resolveResolve profile (expand entity refs)Yes

Prompt Templates

Prefix: /api/prompt-templates

MethodPathDescriptionAuth
POST/resolveResolve template variablesYes
POST/resolve-batchBatch resolve templatesYes
GET/available-fields/{type}List available template fieldsYes

Inventory

Prefix: /api

MethodPathDescriptionAuth
GET/itemsList inventory itemsYes
GET/items/categoriesList item categoriesYes
GET/items/{id}Get item detailsYes
POST/itemsCreate itemYes
PUT/items/{id}Update itemYes
DELETE/items/{id}Delete itemYes
POST/items/import/verseImport items from Verse formatYes
POST/items/import/jsonImport items from JSONYes
GET/items/export/jsonExport items as JSONYes
GET/items/export/verseExport items as VerseYes

Migration and Archive

Prefix: /api

MethodPathDescriptionAuth
POST/migration/importImport full data exportYes (admin)
GET/migration/exportExport all dataYes (admin)
GET/archive/fallbacksList archived fallback dataYes
POST/archive/fallbacks/restoreRestore from archiveYes
POST/archive/fallbacks/cleanupCleanup old archivesYes (admin)

Statistics and Activity

Prefix: /api

MethodPathDescriptionAuth
GET/stats/dashboardDashboard statisticsYes
GET/activity/recentRecent activity feedYes
GET/activity/historyFull activity historyYes
ArchitecturePlugin Development