Radiant Builder API

The Radiant Builder API powers the visual builder and CLI, allowing you to programmatically manage projects, scaffold collections, define access rules, and deploy your backend. All endpoints are protected via a Bearer Token (JWT_SECRET).

POST/projects

Scaffold a Project

Description

Scaffolds a new Radiant project in a temporary workspace, installs dependencies, and prepares it for configuration.

Request Body

Field	Type	Description
name *	string	Name of the project.

Sample Payload

{
  "name": "my-ecommerce-backend"
}

200 OK

{
  "projectId": "8b51a84f-...",
  "apiKey": "rk_8b51a8...",
  "targetDir": "/temps/8b5...",
  "status": "scaffolded",
  "message": "Project my-ecommerce-backend successfully scaffolded with SQLite database."
}

500 Internal Error

{
  "error": "Error scaffolding project..."
}

POST/projects/:projectId/build

Build Project

Description

Triggers `bun run build` inside the specified project directory to compile the Radiant backend into a distributable runtime.

200 OK

{
  "status": "built",
  "stdout": "...",
  "stderr": "",
  "sdkUrl": "/projects/123-abc/sdk"
}

404 Not Found

{
  "error": "Project not found"
}

POST/projects/:projectId/deploy

Deploy Project Locally

Description

Spawns the built project locally on an available port.

200 OK

{
  "status": "deployed",
  "url": "http://localhost:9200",
  "port": 9200,
  "sdkUrl": "/projects/123-abc/sdk"
}

500 Internal Error

{
  "error": "Deploy failed",
  "details": "..."
}

GET/projects/:projectId/sdk

Download Client SDK

Description

Downloads the auto-generated zero-dependency TypeScript Client SDK for the project.

200 OK

// Downloadable TypeScript Source File
import { ... } from "radiant";
...

404 Not Found

{
  "error": "Project not found or SDK not generated"
}

GET/projects/:projectId/collections

List Collections

Description

Returns the JSON schema AST of all collections currently compiled in the project.

200 OK

[
  {
    "name": "users",
    "fields": { ... }
  }
]

POST/projects/:projectId/collections

Create Collection

Description

Generates a new `.radiant` DSL file for a collection, saves it to the project, and automatically runs the compiler to re-generate the schema AST.

Request Body

Field	Type	Description
slug *	string	Collection slug (e.g. users).
fields *	array	Array of field definitions.
auth	boolean	Enable auth on collection.

Sample Payload

{
  "slug": "posts",
  "fields": [
    { "name": "title", "type": "string" },
    { "name": "content", "type": "text", "optional": true }
  ]
}

200 OK

{
  "collection": "posts",
  "status": "compiled",
  "dsl": "\ncollection posts {..."
}

409 Conflict

{
  "error": "Collection already exists"
}

PUT/projects/:projectId/collections/:slug

Update Collection

Description

Updates an existing collection DSL and recompiles the schema.

Request Body

Field	Type	Description
fields *	array	Array of field definitions.
auth	boolean	Enable auth on collection.

Sample Payload

{
  "fields": [
    { "name": "title", "type": "string" }
  ]
}

200 OK

{
  "collection": "posts",
  "status": "compiled",
  "dsl": "..."
}

DELETE/projects/:projectId/collections/:slug

Delete Collection

Description

Deletes a collection and recompiles the project.

200 OK

{
  "collection": "posts",
  "status": "compiled",
  "removed": true
}

POST/projects/:projectId/access

Create Access Rules

Description

Sets access control rules for a given collection and adds them to the project.

Request Body

Field	Type	Description
collection *	string	Target collection.
rules *	object	Map of operations to access logic strings.

Sample Payload

{
  "collection": "users",
  "rules": {
    "read": "true",
    "create": "false"
  }
}

200 OK

{
  "collection": "users",
  "status": "saved",
  "code": "..."
}

PUT/projects/:projectId/access/:collection

Update Access Rules

Description

Updates the access control rules for a specific collection.

Request Body

Field	Type	Description
rules *	object	Map of operations to access logic strings.

Sample Payload

{
  "rules": {
    "read": "ctx.user !== null"
  }
}

200 OK

{
  "collection": "users",
  "status": "saved",
  "code": "..."
}

DELETE/projects/:projectId/access/:collection

Delete Access Rules

Description

Removes access control rules for a collection.

200 OK

{
  "collection": "users",
  "status": "removed"
}

POST/projects/:projectId/hooks

Create Hook

Description

Registers a global application hook (e.g. beforeRequest).

Request Body

Field	Type	Description
slug *	string	Name of the hook file.
code *	string	TypeScript source code for the hook.

Sample Payload

{
  "slug": "log-hook",
  "code": "app.plugins.push({ beforeRequest: (ctx) => console.log('req') });"
}

200 OK

{
  "slug": "log-hook",
  "status": "saved",
  "code": "..."
}

PUT/projects/:projectId/hooks/:slug

Update Hook

Description

Updates the TypeScript code of an existing hook.

Request Body

Field	Type	Description
code *	string	TypeScript source code for the hook.

Sample Payload

{
  "code": "app.plugins.push({ beforeRequest: (ctx) => console.log('updated') });"
}

200 OK

{
  "slug": "log-hook",
  "status": "saved",
  "code": "..."
}

DELETE/projects/:projectId/hooks/:slug

Delete Hook

Description

Removes a hook from the project.

200 OK

{
  "slug": "log-hook",
  "status": "removed"
}

PUT/projects/:projectId/config

Update Config

Description

Updates the project's config.radiant file.

Request Body

Field	Type	Description
data *	object	Configuration options.

Sample Payload

{
  "apiPrefix": "/api/v2"
}

200 OK

{
  "status": "compiled",
  "dsl": "config {\n  apiPrefix: \"/api/v2\";\n}\n"
}

POST/projects/:projectId/db-sync

Database Sync

Description

Runs the `db:sync` CLI command on the project to synchronize the schema with the underlying database.

200 OK

{
  "status": "synced",
  "stdout": "...",
  "stderr": ""
}