Projects API

Every organization can create multiple projects. Each project gets an isolated PostgreSQL database, storage bucket, API keys, and full lifecycle management.

🏗️

Isolated by Design

Each project gets its own PostgreSQL database (zbaas_<org_id>_<slug>), ensuring complete data isolation between projects.

Project Management

Create Project

POST /projects

{
  "name": "My App",
  "slug": "my-app",
  "description": "Production backend for My App"
}

// Response — database auto-provisioned
{
  "id": "uuid",
  "name": "My App",
  "slug": "my-app",
  "db_name": "zbaas_org123_my_app",
  "status": "active"
}

List Projects

GET /projects

Authorization: Bearer <token>
// Returns all projects in the user's organization

Get by Slug

GET /projects/by-slug/{slug}

// Useful for resolving dashboard URLs to project IDs

Update & Delete

PATCH /projects/{project_id}

{ "name": "Updated Name", "description": "New desc" }

DELETE /projects/{project_id}

// Drops database, purges storage, removes all associated data

API Keys

Each project can have multiple API keys for SDK, CLI, and REST access. Keys are hashed in the database — the plain key is shown only once at creation time.

Generate Key

POST /projects/{project_id}/keys

{ "name": "production-key" }

// Response (plain key shown ONCE)
{
  "id": "uuid",
  "name": "production-key",
  "key": "zmesh_pk_abc123..."
}

List & Revoke

GET /projects/{project_id}/keys

// Returns metadata only (ID, Name, Created) — never the key

DELETE /projects/{project_id}/keys/{key_id}

// Immediately revokes the key

Migrations

Version-controlled schema changes with up/down support. Create migrations from the dashboard or CLI, apply forward, or rollback.

Create Migration

POST /projects/{project_id}/database/migrations

{
  "name": "add_posts_table",
  "up_sql": "CREATE TABLE posts (id SERIAL PRIMARY KEY, title TEXT);",
  "down_sql": "DROP TABLE posts;"
}

List / Apply / Rollback

GET /projects/{project_id}/database/migrations

// Returns all migrations with applied/pending status

POST /projects/{project_id}/database/migrations/{id}/up

// Applies the migration (runs up_sql)

POST /projects/{project_id}/database/migrations/{id}/down

// Rollback the migration (runs down_sql)

Row-Level Security (RLS)

Enable PostgreSQL RLS on any table and manage policies via the API. Policies control which rows users can access based on JWT claims.

Enable / Disable RLS

POST /projects/{project_id}/database/rls/{table}/enable

// Runs: ALTER TABLE <table> ENABLE ROW LEVEL SECURITY

POST /projects/{project_id}/database/rls/{table}/disable

Manage Policies

POST /projects/{project_id}/database/rls/{table}/policies

{
  "name": "users_own_data",
  "command": "ALL",
  "using": "(auth.uid() = user_id)",
  "check": "(auth.uid() = user_id)"
}

GET /projects/{project_id}/database/rls/{table}/policies

// Lists all policies on the table

DELETE /projects/{project_id}/database/rls/{table}/policies/{policy_name}

PostgreSQL Extensions

Enable popular Postgres extensions directly from the dashboard or API.

GET /projects/{project_id}/database/extensions

// Returns: available extensions with enabled/disabled status
// Supports: pgvector, pg_trgm, uuid-ossp, hstore, postgis, etc.

POST /projects/{project_id}/database/extensions/{ext_name}/enable

POST /projects/{project_id}/database/extensions/{ext_name}/disable

Index Management

GET /projects/{project_id}/database/tables/{table}/indexes

// Lists all indexes on the table

POST /projects/{project_id}/database/tables/{table}/indexes

{
  "column": "email",
  "type": "btree",
  "unique": true
}
// Supports: btree, hash, gist, gin

DELETE /projects/{project_id}/database/indexes/{index_name}

Backup & Full-Text Search

Database Backup

POST /projects/{project_id}/database/backup

// Returns a downloadable pg_dump SQL file

Full-Text Search

POST /projects/{project_id}/database/tables/{table}/search

{
  "query": "hello world",
  "columns": ["title", "body"],
  "limit": 20
}
// Uses PostgreSQL tsvector for ranked full-text search

Database Branches

Create isolated database branches for development and staging. Branch from production, test changes, and merge back.

POST /projects/{project_id}/branches

{ "name": "feature-user-roles" }
// Clones the current database schema into a new branch

GET /projects/{project_id}/branches

POST /projects/{project_id}/branches/{branch_name}/merge

// Merges branch schema changes back to the parent database

DELETE /projects/{project_id}/branches/{branch_name}

Database Health

GET /projects/{project_id}/db/health

// Returns comprehensive health report:
// - Table bloat analysis
// - Missing indexes
// - Slow query detection
// - Connection stats