BlueForge Docs

Projects CRUD

Manage platform projects. Each project provisions an isolated Postgres database, auto-generated REST API, auth, storage, and compute.

Endpoint

MethodPathAuthIdempotent
POST
/api/platform/projects
tenant Bearerno (provisions Postgres DB)
GET
/api/platform/projects
tenant Beareryes
GET
/api/platform/projects/:id
tenant Beareryes
DELETE
/api/platform/projects/:id
tenant Beareryes (subsequent calls return 404)

Parameters

NameTypeRequiredDefaultNotes
name
stringyes—human label; 2–64 characters; slug auto-generated
plan
stringno
"free"
"free"
, 
"starter"
, 
"pro"
, or 
"team"
id
stringyes*—path parameter for GET/DELETE; project ID (
prj_xxx
)

*The 

id
parameter is required for the GET and DELETE operations.

Response

// POST /projects — Create
{
  project: {
    id: string          // "prj_xxx"
    name: string
    slug: string        // auto-generated from name
    status: string      // "active" | "creating" | "deleted"
    plan: string        // "free" | "starter" | "pro" | "team"
    region: string      // e.g. "eu-west-1"
    createdAt: string   // ISO 8601
  },
  credentials: {
    connectionString: string
    poolerConnectionString: string
    apiUrl: string
    anonKey: string
    serviceRoleKey: string
  }
}

// GET /projects — List
{
  projects: Array<{
    id: string
    name: string
    slug: string
    status: string
    plan: string
    region: string
    postgrest_status: string | null
    created_at: string
    updated_at: string
  }>
}

// GET /projects/:id — Detail
{
  project: { /* same shape as list item */ }
  apiKeys: Array<{ id: string; name: string; key_prefix: string }>
  recentBackups: Array<{ id: string; started_at: string; status: string }>
}

// DELETE /projects/:id — Soft-delete
{
  deleted: true
  projectId: string
}

Examples

# Create a project
curl -X POST https://api.blueforge.studio/api/platform/projects \
  -H "Authorization: Bearer $BF_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "plan": "pro"}'

# List all projects
curl https://api.blueforge.studio/api/platform/projects \
  -H "Authorization: Bearer $BF_TENANT_KEY"

# Get project detail
curl https://api.blueforge.studio/api/platform/projects/prj_xxx \
  -H "Authorization: Bearer $BF_TENANT_KEY"

# Soft-delete a project
curl -X DELETE https://api.blueforge.studio/api/platform/projects/prj_xxx \
  -H "Authorization: Bearer $BF_TENANT_KEY"

import { Client } from "@blueforge/client"

// Create
const { project, credentials } = await client.projects.create({
  name: "My App",
  plan: "pro"
})

// List
const { projects } = await client.projects.list()

// Get detail
const detail = await client.projects.get("prj_xxx")

// Delete
await client.projects.delete("prj_xxx")

Pitfalls

  • Slug is auto-generated from the project name. Slugs must be unique across all tenants — a conflict returns HTTP 409.
  • Plan limits are enforced at creation time: Free (2 projects, 500 MB), Starter (5, 2 GB), Pro (20, 10 GB), Team (50, 50 GB).
  • The POST endpoint is not idempotent — each call provisions a new Postgres database.
  • DELETE is a soft-delete. The database and resources are not immediately destroyed.
  • Credentials (connection strings, keys, etc.) are returned only on creation. Subsequent GET calls return project metadata only.

See also

Tested against

  • @blueforge/platform-api: 2.4.1
  • Last verified: 2026-07-15