projects.create

Create a new platform project (provisions DB + API keys).

Create a new BlueForge platform project. Each project gets an isolated PostgreSQL database, auto-generated REST API, API keys, and resource quotas.

Endpoint

Method	Path	Auth	Idempotent
POST	`/api/platform/projects`	Bearer {key}	no

Parameters

Name Type Required Default Notes

Name	Type	Required	Default	Notes
`name`	string	yes	—	Unique within tenant; slug auto-derived
`plan`	enum	no	`free`	`free` \| `starter` \| `pro` \| `team`

name

string

yes

—

Unique within tenant; slug auto-derived

plan

enum

free

free

starter

pro

team

Response

interface Project {
  id: string
  name: string
  slug: string
  status: 'provisioning' | 'ready' | 'error'
  plan: string
  created_at: string
}

On success, the response also includes

credentials

with the connection string, pooler URL, API URL, and service role key.

Examples

cURL:

curl -X POST https://api.blueforge.studio/api/platform/projects \
  -H "Authorization: Bearer $BF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "plan": "free"}'

SDK:

import { Client } from "@blueforge/client"
const client = new Client({ apiKey: process.env.BF_API_KEY! })
const project = await client.projects.create({ name: "my-project" })

CLI:

forge project create my-project --plan free

Error handling:

import { Client, RateLimitError } from "@blueforge/client"
try {
  await client.projects.create({ name: "my-project" })
} catch (e) {
  if (e instanceof RateLimitError) {
    await sleep(e.retryAfter * 1000)
    return retry()
  }
  throw e
}

Pitfalls

409 Conflict — project name must be unique within the tenant. Collisions return 409.

Async provisioning —

created_at

≠ "ready to query". Poll

GET /api/platform/projects/:id

until

status === 'ready'

Credentials shown once — connection details are returned in the create response only. Save them immediately.
Rate limit — 100 req/min per project key. Retry with exponential backoff on 429.
Plan limits — Free plan: 2 projects, 500 MB storage. Check
```
GET /api/platform/projects
```
for usage.

Tested against

{auto-injected}