API Reference

Configure the API base URL per environment; /v1 lives under it. Locally it is http://localhost:3000.

Fast, lightweight health: app version, data mode, database + provider modes. Always 200.

Readiness probe. In database mode verifies a live connection; returns 503 until ready.

Liveness probe. Returns 200 while the process is alive.

Richer secret-safe diagnostics including the startup-check report (app session / demo).

List design products available to an authenticated API client.

Create a project from a design entitlement without auto-billing.

Provision starter files and GitHub Actions workflow into the connected repository.

Trigger deployment for a provisioned, entitled project.

Report whether AI generation is running in demo or real provider mode.

Create an AI generation request that produces reviewable artifacts.

Create a reviewable project version from accepted artifacts.

Approve a project version before provisioning or deployment.

Provision an approved project version through the existing GitHub Actions flow.

Register an outbound webhook endpoint for project and deployment lifecycle events.

All /v1 routes require a workspace-scoped API key.

Authenticated /v1 requests are always scoped to the API key workspace.

Demo memory mode remains available while durable database mode is introduced for PostgreSQL-backed runtimes.

Required for AI generation creation, run/cancel, and artifact review actions.

Required for project version creation, approval, provisioning, and deployment.

Required for repository connection creation and updates.

Required for webhook endpoint creation, updates, and deletes.

Required for usage and rate limit inspection endpoints.

External API successes always return a consistent envelope.

Errors share a consistent shape; details carries a requestId (also the X-Request-Id header) for support/tracing. Existing clients that ignore it are unaffected.

Workspace and API-key rate limits are surfaced when straightforward.

API clients cannot bypass artifact review or project version approval.

Outbound webhooks are signed using HMAC(timestamp + payload).

Missing or invalid API key.

The API key lacks the scope required for this action.

The workspace/plan does not have external API access enabled.

An active entitlement is required to create, provision, or deploy.

Workspace/API-key rate limit exceeded; see X-RateLimit-* and retryAfterSeconds.

Private beta access is required; an accepted beta invite is needed.

The action is blocked by a policy/entitlement decision; see details.requiredAction.

The runtime is not ready (e.g. database mode without a reachable database).

Database mode is configured but the database is unreachable.

A required provider (GitHub/Stripe/AI) real mode is enabled but not fully configured.

Unexpected server error; quote error.details.requestId when reporting it.

Blossum is in a controlled private beta. Operators create invites in /app/admin/beta-invites; invitees accept via /beta/invite/<token> (email delivery is manual for now).

List feedback for the current workspace (app session / demo).

Submit feedback (category, severity, title, description). Captures the request id for tracing.

In-app feedback form for beta users; blocked states link here.

GitHub/billing/AI may run in demo mode; real modes require external configuration. billingOrdersSubscriptions remains documented_partial in database mode.

Set BLOSSUM_DATA_MODE=database and run db:migrate before startup.

Set BLOSSUM_API_URL / web PUBLIC_API_URL and CORS_ORIGINS to your web origin(s).

SESSION_SECRET and API_KEY_SECRET are required in hosted mode.

Confirm /api/health, /api/ready, and /api/live before sending traffic.

Create a workspace API key in /app/api-keys; it is shown once and stored hashed.