Backend API Endpoint Catalog

All paths include the global /api prefix. Routes marked (auth) require Authorization: Bearer <accessToken> via BackendAuthGuard.

Health & Root

• GET /api – Root data.
• GET /api/health – Service health payload.

Authentication

• POST /api/auth/register – Create account, returns tokens.
• POST /api/auth/login – Login, returns tokens.
• GET /api/auth/profile (auth) – Current user profile.

Users

• GET /api/users/me/journey (auth) – Fetch personal journey snapshot.
• PUT /api/users/me/journey (auth) – Update personal journey analytics.

AI Core

• POST /api/ai/openai/chat (auth) – OpenAI chat completions.
• POST /api/ai/anthropic/messages (auth) – Anthropic Claude messages.
• POST /api/ai/google/generate (auth) – Google model generation.
• GET /api/ai/usage (auth) – Usage for current user (days query default 30).
• GET /api/ai/usage/providers (auth) – Usage grouped by provider.
• POST /api/ai/generate/widget (auth) – Widget code generation (stubbed).
• POST /api/ai/generate/module (auth) – Module code generation (stubbed).

AI Learning

• POST /api/ai/learning/generations – Record a generation.
• POST /api/ai/learning/generations/:generationId/feedback – Submit feedback.
• GET /api/ai/learning/generations – History (spaceId, limit).
• GET /api/ai/learning/generations/examples/:generationType – Successful examples.
• GET /api/ai/learning/mappings – All NLP→property mappings.
• GET /api/ai/learning/mappings/phrase – Query mappings by phrase.
• POST /api/ai/learning/mappings/:mappingId/usage – Track mapping success.
• GET /api/ai/learning/theme-context – Theme context list.
• GET /api/ai/learning/theme-context/prompt – Prompt-friendly theme context.
• GET /api/ai/learning/context/combined – Theme + mapping prompt bundle.
• GET /api/ai/learning/metrics – Learning metrics (optional spaceId).

AI Agents (task system)

• Base /api/ai-agents/* (auth).
• POST /tasks – Create task.
• GET /tasks – List tasks (filters: status, type, tenantId, spaceId, limit, offset).
• GET /tasks/:id – Task by id.
• PUT /tasks/:id – Update task.
• DELETE /tasks/:id – Delete task.
• PUT /tasks/:id/pause|resume|cancel – Control lifecycle.
• POST /tasks/:id/feedback – Submit feedback.
• POST /tasks/:id/decomposition – Set task steps.
• POST /tasks/:id/record-outcome – Persist outcome for learning.
• Sessions: POST /tasks/:id/sessions, GET /tasks/:id/sessions, GET /tasks/:id/sessions/active, GET /tasks/:taskId/sessions/:sessionId, PUT /tasks/:taskId/sessions/:sessionId/complete|fail|interrupt, POST /tasks/:taskId/sessions/:sessionId/decisions|errors, PUT /tasks/:taskId/sessions/:sessionId/metrics.
• Handoff: GET /tasks/:id/handoff, GET /tasks/:id/handoff/prompt.
• Metrics: GET /metrics, GET /insights, POST /export.

AI Agents (public, no auth)

• GET /api/ai-agents/vector/stats – Vector memory stats.
• GET /api/ai-agents/stats/summary – Tier summary.
• GET /api/ai-agents/patterns – Learned patterns (placeholder).

Analytics

• GET /api/analytics/journey (auth) – Current user journey.
• PUT /api/analytics/journey (auth) – Sync journey batch.
• GET /api/analytics/stats (auth) – Platform analytics (admin).
• POST /api/analytics/journey/beacon – Beacon-friendly journey sync (accepts cookie or userId).

Assets (pages/widgets/flows/components)

• Base /api/assets (auth), type in path must be pages|widgets|flows|components.
• GET /api/assets/:type – List (supports universeId/galaxyId/isTemplate/tags filters).
• GET /api/assets/:type/:id – Fetch asset.
• POST /api/assets/:type – Create (ownerId set from token).
• PUT /api/assets/:type/:id – Update.
• DELETE /api/assets/:type/:id – Delete.
• POST /api/assets/:type/:id/fork – Duplicate asset (requires name).

Themes

• GET /api/themes – List or paginate (page, limit, sortBy, sortOrder).
• GET /api/themes/search – Search (q).
• GET /api/themes/space/:spaceId – Themes by space.
• GET /api/themes/active – Active theme id (global).
• GET /api/themes/:themeId/exists – Existence check.
• GET /api/themes/:themeId – Theme details.
• POST /api/themes (auth) – Create/save theme.
• PUT /api/themes/:themeId (auth) – Update theme.
• PUT /api/themes/active (auth) – Set active theme.
• DELETE /api/themes/:themeId (auth) – Delete theme.
• DELETE /api/themes (auth) – Danger: delete all themes.
• GET /api/themes/stats/count – Count summary.

Spaces & Universes (tenant workspace)

• Base /api/spaces (auth).
• GET /api/spaces/me – Get current user space.
• GET /api/spaces/slug/:slug – Lookup by slug.
• POST /api/spaces – Create space.
• PUT /api/spaces/:spaceId – Update space (name, description, slug, universeIds, settings, themeSystem).
• DELETE /api/spaces/:spaceId – Remove space.
• POST /api/spaces/initialize – Ensure space exists for user.
• POST /api/spaces/:spaceId/migrate-metadata – Populate missing metadata.
• Theme management: POST /api/spaces/:spaceId/themes, POST /api/spaces/:spaceId/themes/clone, GET /api/spaces/:spaceId/theme-system.
• Migration helpers: POST /api/spaces/:spaceId/migrate-database, POST /api/spaces/:spaceId/migrate-collections.
• Universes: GET /api/spaces/:spaceId/universes, POST /api/spaces/:spaceId/universes, PUT /api/spaces/:spaceId/universes/:universeId, GET /api/spaces/:spaceId/universes/:universeId, DELETE /api/spaces/:spaceId/universes/:universeId.
• Space pages: GET /api/spaces/:spaceId/space-pages, POST /api/spaces/:spaceId/space-pages, GET /api/spaces/:spaceId/space-pages/by-slug/:slug, GET /api/spaces/:spaceId/space-pages/:pageId, PUT /api/spaces/:spaceId/space-pages/:pageId, DELETE /api/spaces/:spaceId/space-pages/:pageId, GET /api/spaces/:spaceId/space-pages-stats.

Universe Data (per-space/per-universe collections)

• Base /api/spaces/:spaceId/universes/:universeId (auth).
• GET /api/spaces/:spaceId/universes/:universeId/collections – List collections.
• POST /api/spaces/:spaceId/universes/:universeId/data/:collection/query – Query records (filter/sort/pagination in body).
• POST /api/spaces/:spaceId/universes/:universeId/data/:collection/insert – Insert record.
• PUT /api/spaces/:spaceId/universes/:universeId/data/:collection/:recordId – Update record by ObjectId.
• DELETE /api/spaces/:spaceId/universes/:universeId/data/:collection/:recordId – Delete record.
• POST /api/spaces/:spaceId/universes/:universeId/data/:collection/export – Export to CSV (StreamableFile).
• POST /api/spaces/:spaceId/universes/:universeId/data/:collection/aggregate – Aggregation pipeline.

Space Modules (flat module collection)

• Base /api/spaces/:spaceId/modules (auth).
• GET / with filters (scope, universeId, type, extendsGlobal, moduleId, widgetId, search, limit, offset).
• GET /stats – Module stats.
• GET /for-universe/:universeId – Shared + universe modules.
• GET /pages/:universeId – Page modules.
• GET /navigation – Navigation modules (optional universeId).
• GET /by-type/:type – Modules by type.
• GET /extends/:globalModuleId – Modules extending a global module.
• GET /from-widget/:widgetId – Modules derived from widget.
• GET /:moduleId – Module by id.
• POST /batch – Upsert many modules.
• POST / – Create module.
• PATCH /:moduleId – Update module.
• PATCH /:moduleId/activate or /deactivate – Toggle active.
• DELETE /:moduleId – Delete module.
• DELETE /for-universe/:universeId – Delete universe-specific modules.
• POST /initialize-indexes – Create indexes.

Modules Configuration (tenant-aware)

• Base /:tenantId/modules.
• GET /api/:tenantId/modules/configuration – All module configs.
• GET /api/:tenantId/modules/configuration/:moduleId – Config by module.
• PUT /api/:tenantId/modules/configuration/:moduleId – Update config.

Universal Modules (universe-scoped unified schema v3)

• Base /:spaceId/universes/:universeId/modules.
• POST /api/:spaceId/universes/:universeId/modules – Create/install module (supports moduleId/pageId/layout/ai).
• GET /api/:spaceId/universes/:universeId/modules – Query modules (type, parentId, position, tags, isActive, search, sort, pagination, moduleId, capability, keyword).
• GET /api/:spaceId/universes/:universeId/modules/:moduleId – Module by id.
• GET /api/:spaceId/universes/:universeId/modules/:moduleId/tree – Module with recursive children.
• PUT /api/:spaceId/universes/:universeId/modules/:moduleId – Update module.
• DELETE /api/:spaceId/universes/:universeId/modules/:moduleId – Delete (optional removeChildren).
• POST /api/:spaceId/universes/:universeId/modules/:moduleId/move – Move between parents / reorder.

Unified Modules v2 (structural/content/packaged/ux-library discovery)

• Base /api/modules/unified (auth).
• GET /api/modules/unified/all – Discover all modules across sources (filters: spaceId, universeId, type, status, search).
• GET /api/modules/unified/:id – Module details (spaceId query).
• POST /api/modules/unified/install – Install any module type.
• POST /api/modules/unified/clone – Clone into variant.
• PUT /api/modules/unified/:id/config – Update config.
• DELETE /api/modules/unified/:id – Uninstall.

Global Modules (platform-wide catalog)

• Base /api/global-modules (auth).
• GET / – List (supports search via query).
• GET /stats – Summary stats.
• GET /core – Core module list.
• GET /by-type/:type – Filter by type.
• GET /by-category/:category – Filter by category.
• GET /by-capabilities – Filter by capability flags.
• GET /:id – Module by id.
• POST / – Create module.
• POST /batch – Batch create.
• POST /upsert – Upsert module.
• PATCH /:id – Update module.
• PATCH /:id/activate or /deactivate – Toggle status.
• DELETE /:id – Delete.
• POST /seed – Seed defaults.
• POST /migrate – Migration helper.

Global Resources (widgets, flows, templates)

• Controllers: @Controller('global-widgets'), global-flows, global-templates (auth).
• Global widgets:
  • GET /api/global-widgets – Search (query filters).
  • GET /api/global-widgets/:id – Fetch widget.
  • POST /api/global-widgets – Create.
  • POST /api/global-widgets/upsert – Upsert.
  • POST /api/global-widgets/seed – Seed.
  • DELETE /api/global-widgets/:id – Delete.
• Global flows:
  • GET /api/global-flows – Search.
  • GET /api/global-flows/:id – Fetch.
  • POST /api/global-flows – Create.
  • POST /api/global-flows/upsert – Upsert.
  • POST /api/global-flows/seed – Seed.
  • DELETE /api/global-flows/:id – Delete.
• Global templates:
  • GET /api/global-templates – Search.
  • GET /api/global-templates/featured – Featured set.
  • GET /api/global-templates/:id – Fetch.
  • POST /api/global-templates – Create.
  • POST /api/global-templates/upsert – Upsert.
  • POST /api/global-templates/:id/use – Track usage.
  • POST /api/global-templates/seed – Seed.
  • DELETE /api/global-templates/:id – Delete.
  • GET /api/global-templates/stats – Stats.

Marketplace (public modules)

• Base /api/marketplace.
• GET /modules – Browse marketplace (filters: category, tags, minRating, verified, search, sortBy, limit, offset).
• GET /modules/:id – Module listing details.
• POST /modules (auth) – Publish module listing.
• GET /modules/:id/reviews – Reviews.
• POST /modules/:id/reviews (auth) – Add review.

Widgets

• Base /api/spaces/:spaceId/widgets (auth).
• GET / – List widgets.
• GET /:widgetId – Widget by id.
• POST / – Create widget.
• PUT /:widgetId – Update widget.
• DELETE /:widgetId – Delete widget.
• GET /:widgetId/variants – Variants for widget.
• GET /:widgetId/embeddable – Embeddable payload.
• POST /:widgetId/variants – Create variant (legacy in widget controller).
• PUT /:widgetId/variants/:variantId – Update variant.
• GET /ai-context – AI context for widgets.

Widget Variants (dedicated controller)

• Base /api/spaces/:spaceId/widgets/:widgetId/variants.
• GET / – List variants.
• GET /:variantId – Variant by id.
• POST / – Create variant.
• PUT /:variantId – Update variant.
• DELETE /:variantId – Delete variant.
• POST /:variantId/set-default – Mark default.
• POST /:variantId/duplicate – Duplicate variant.

Core Widget Variants

• Base /api/widgets/core-variants.
• GET / – All core variants.
• GET /:widgetType – Variants for widget type.
• POST /reseed – Reseed core variants.
• GET /stats/summary – Summary counts.

Widget Modules

• Base /api/spaces/:spaceId/widget-modules.
• GET / – List modules (query filters).
• GET /search – Search modules.
• GET /type/:type, /category/:category, /source/:widgetId, /:moduleId.
• POST / – Create widget module.
• PUT /:moduleId – Update.
• DELETE /:moduleId – Delete.
• POST /:moduleId/install – Track install.
• POST /:moduleId/usage/universe – Track universe usage.

Properties (space-scoped)

• Base /api/spaces/:spaceId/properties.
• GET / – List properties.
• GET /search – Search (q, category, controlType, widgetType).
• GET /widget-type/:widgetType – Applicable properties.
• GET /templates – List templates.
• GET /templates/ai-context – AI context bundle.
• GET /templates/widget-type/:widgetType – Templates for widget type.
• GET /templates/:templateId – Template by id.
• GET /core-sync – Hydrated properties + templates payload.
• POST /templates – Create template.
• POST /templates/seed – Seed built-ins.
• PUT /templates/:templateId – Update template.
• DELETE /templates/:templateId – Delete template.
• POST /templates/:templateId/usage – Track template usage.
• POST /:propertyId/usage – Track property usage.
• GET /:propertyId – Property by id.
• POST / – Create property.
• POST /batch – Batch create.
• PUT /:propertyId – Update property.
• DELETE /:propertyId – Delete property.

Core Properties (read-only, global)

• Base /api/core.
• GET /properties – List core properties.
• GET /properties/search – Search core properties (q).
• GET /properties/category/:category – By category.
• GET /properties/widget/:widgetType – For widget type.
• GET /properties/:propertyId – Core property by id.
• GET /templates – Core property templates.
• GET /templates/widget/:widgetType – Core templates by widget.
• GET /templates/:templateId – Core template by id.
• GET /ai-context – AI property context string.

Data Storage Helpers

• Base /api/storage (auth).
• POST /mongodb/test – Test Mongo connection.
• POST /mongodb/collections – List collections (connection info).
• POST /mongodb/query – Run ad-hoc query.
• POST /mongodb/insert – Insert document.
• PUT /mongodb/update – Update documents.
• DELETE /mongodb/delete – Delete documents.
• Sync helpers (space db): POST /sync/:collection, PUT /sync/:collection/:documentId, DELETE /sync/:collection/:documentId, GET /sync/:collection/:documentId.

Deployment (tenant scoped)

• Base /api/:tenantId/deployment.
• POST /:universeId/deploy – Deploy universe (config).
• GET /:deploymentId/status – Deployment status.
• POST /:universeId/undeploy – Remove deployment.
• GET /list – List deployments for tenant.

Universe Deployment (auth)

• Base /api/universes.
• POST /initialize – Initialize universe (create collections).
• POST /:id/publish – Publish universe (spaceId in body).
• POST /:id/unpublish – Unpublish universe.
• PATCH /:id/deployment-config – Update deployment config.
• GET /:id/deployment-status – Deployment status.
• POST /:id/verify-domain – Verify domain.

Marketplace/Commerce

• Products:
  • POST /api/products – Create (headers: x-space-id, x-tenant-id).
  • GET /api/products – List (filters via query).
  • GET /api/products/featured – Featured products.
  • GET /api/products/low-stock – Low stock items.
  • GET /api/products/slug/:slug – By slug.
  • GET /api/products/:id – By id.
  • PUT /api/products/:id – Update.
  • PATCH /api/products/:id/inventory – Update inventory.
  • DELETE /api/products/:id – Delete.
• Orders:
  • POST /api/orders – Create (requires x-space-id, x-tenant-id).
  • GET /api/orders – List orders.
  • GET /api/orders/statistics – Order stats.
  • GET /api/orders/number/:orderNumber – By order number.
  • GET /api/orders/:id – By id.
  • PATCH /api/orders/:id/status – Update status.
  • PATCH /api/orders/:id/payment – Update payment status.
  • PATCH /api/orders/:id/tracking – Update tracking info.

Widgets Marketplace (Module Marketplace)

• See Marketplace section above for /api/marketplace/*.

Modules Marketplace Seeders (Widget Variants/Core)

• Covered in widget variant sections.

Singularity (flow engine)

• Base /api/singularity.
• POST /flows – Create flow.
• GET /flows/:id – Get flow.
• GET /flows – List flows.
• GET /flows/search – Search flows.
• PUT /flows/:id – Update flow.
• DELETE /flows/:id – Delete flow.
• POST /flows/:id/execute – Execute flow with params/context.
• POST /flows/execute-direct – Execute ad-hoc flow payload.
• POST /executions/:id/cancel – Cancel execution.
• GET /flows/:id/executions – Execution history.
• GET /executions/recent – Recent executions.
• POST /flows/:id/validate – Validate flow.
• GET /statistics – Flow stats.
• GET /export – Export flows (bulk).
• POST /import – Import flows.

Singularity Events

• Base /api/singularity/events.
• POST /bindings – Create event binding.
• GET /bindings – List bindings.
• GET /bindings/flow/:flowId – Bindings for flow.
• DELETE /bindings/:id – Delete binding.
• GET /types – Supported types.
• POST /emit – Emit event (direct).
• POST /page-module/:moduleId/:trigger – Emit page module trigger.
• POST /widget/:widgetId/:eventName – Emit widget event.
• POST /module/:moduleId/:eventName – Emit module event.
• GET /standard-types – Standardized event types.

UI Builder (experimental)

• Base /api/ui-builder.
• POST /components – Create component.
• GET /components/:id – Get component.
• PUT /components/:id – Update component.
• DELETE /components/:id – Delete component.
• POST /components/:id/export – Export to widget/module library.
• GET /components/library – Library listing.
• POST /components/:id/code – Generate code (TS/template/styles).
• GET /components/:id/preview – Preview HTML/CSS.
• POST /components/:id/validate – Validate component.
• POST /components/:id/duplicate – Duplicate component.
• GET /categories – Component categories.
• GET /statistics – Component stats.

Ferrari (multi-pillar project generator)

• Base /api/ferrari.
• POST /projects/generate – Generate multi-pillar project (AI stub).
• GET /projects/:id – Project by id.
• POST /projects/:id/deploy – Deploy project.
• GET /projects/:id/progress – Generation progress.
• GET /projects – List projects.
• GET /templates – Available templates.
• POST /projects/from-template – Instantiate from template.
• GET /statistics – Platform stats.

Modules Marketplace Widgets (Embeddables)

• Covered under Marketplace and Global Resources.

Global Module Discovery (unified)

• Covered under Unified Modules.

Storage/Database Benchmarks

• GET /api/benchmark – Benchmark info.
• POST /api/benchmark/run – Run full benchmark suite.

Deployment (Universe) – Additional

• See Universe Deployment and Deployment sections above for both tenant-scoped and global helper routes.

Misc Controllers

• Realtime gateway advertised at ws://<host>:3000/sync; YJS at ws://<host>:3000/yjs (from bootstrap).

For quick navigation, refer back to /GoGrab-Space/sessions/session-13/README.