Reference

REST API

The Dreambase API at api.dreambase.dev is the backbone of the platform. It backs the app, stores every project, and orchestrates every platform service.

Overview

The API is a NestJS application exposing REST endpoints, backed by MongoDB through Prisma. It authenticates users with Clerk and authorizes access using organization membership and roles. The Dreambase app talks to it for everything; the platform services call back into it to report results.

Authentication

User requests are authenticated with Clerk (a validated JWT). Service callbacks are authenticated with service tokens issued per event and limited to specific scopes. Protected endpoints always check organization membership before granting access.

Core domain

The API models the platform around a handful of related entities:

  • Organizations & users — users belong to organizations through memberships with an OWNER or MEMBER role. Organizations own designs, service definitions, and members.
  • Designs & services — designs contain services, which are instances of service definitions positioned on the canvas.
  • Service definitions & marketplace — reusable templates that can be organization-specific or public. They carry webhook URLs, function schemas, scopes, and metadata.
  • Environments & deployments — environments provide isolated contexts; deployments are running instances of services with status, logs, outputs, and environment variables.

Orchestration & events

Beyond storing data, the API is the conductor. It dispatches webhook events — SERVICE_ADDED, DEPLOYMENT_CREATED, FUNCTION_CALL, HEALTH_CHECK, and others — to the platform services, each with a rich payload describing the service, deployment, environment, and design. Services authenticate their callbacks with the scoped service token carried by the event.

Code generation

Alongside generating the Prisma database client, the API can generate client code — JavaScript/TypeScript service libraries with environment-specific context baked in — so services and apps have typed access to the platform.

You rarely call it directly

Day to day, you interact with the API through the Dreambase app. This reference exists so you understand what happens behind the canvas — and so you can build your own service integration against the same contract.