Skip to content

Projects API

Projects contain environments; environments contain services (sites and databases). Every organization has a Default project (is_default: true). Environments are addressed by slug or id.

{"id": "01j…", "name": "Shop", "description": null, "icon": null, "is_default": false, "created_at": "…",
"environments": [{"id": "01j…", "project_id": "01j…", "name": "production", "slug": "production",
"is_production": true, "forked_from_id": null, "services_count": 3, "created_at": "…"}]}

GET /api/v1/projects · GET /api/v1/projects/{project} — projects.view

Section titled “GET /api/v1/projects · GET /api/v1/projects/{project} — projects.view”

List projects, or show one with its environments.

Body {name, description?, icon?}. Creates the project with its production environment. 201.

Terminal window
curl -X POST https://falak.example.com/api/v1/projects \
-H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"name": "Shop"}'

PATCH /api/v1/projects/{project} · DELETE /api/v1/projects/{project} — projects.manage

Section titled “PATCH /api/v1/projects/{project} · DELETE /api/v1/projects/{project} — projects.manage”

Rename or update the description and icon. Only empty, non-default projects can be deleted (422 otherwise).

GET /api/v1/projects/{project}/environments — projects.view

Section titled “GET /api/v1/projects/{project}/environments — projects.view”

The project’s environments.

POST /api/v1/projects/{project}/environments — projects.manage

Section titled “POST /api/v1/projects/{project}/environments — projects.manage”

Body {name, from_environment_id?}. 201 {data, warnings[]}.

With from_environment_id (which also needs sites.create), every site of that environment is copied — configuration, deploy script, toggles, shared paths and variables, no servers, push-to-deploy off — at the same canvas position and with the same service name. Databases are not copied.

Terminal window
curl -X POST https://falak.example.com/api/v1/projects/01j…/environments \
-H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"name": "staging", "from_environment_id": "01j…"}'

PATCH|DELETE /api/v1/projects/{project}/environments/{environment} — projects.manage

Section titled “PATCH|DELETE /api/v1/projects/{project}/environments/{environment} — projects.manage”

Rename (the slug follows). Only empty, non-production environments can be deleted.

POST /api/v1/projects/{project}/environments/{environment}/services — projects.manage + databases.manage / sites.create

Section titled “POST /api/v1/projects/{project}/environments/{environment}/services — projects.manage + databases.manage / sites.create”

The canvas’ + Create. For a database:

Request body
{"kind": "database", "engine": "postgresql", "server_id": "01k…", "name": "shop-db",
"version": "17", "memory_mb": 1024, "disk_gb": 20}

engine is postgresql, mysql, mariadb, redis or valkey. Falak creates a database container on the server (a Falak image of the major, default the engine’s newest), joined to the environment’s network. memory_mb defaults to 512 (128 for Redis / Valkey), disk_gb to 10 (2). SQL engines get a database and a user named after it; Redis / Valkey their keyspace and default user, with optional eviction (default noeviction) and persistence (rdb default, aof, none). A major this release ships no pinned image of is a 422 on version.

For a site, the body is POST /api/v1/sites’ body with "kind": "site". 201 {data: <canvas service>, warnings[]}; the service is provisioning until the container runs.

POST /api/v1/sites accepts project_id and environment_id. Without them, the site lands in the Default project’s production environment. See Sites API.

Site variables may contain ${{ <service>.<KEY> }}. They resolve at deploy time against services of the same environment. Database services expose DATABASE_URL/DB_*; Redis and Valkey instances expose REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_PASSWORD and REDIS_CLIENT. Hosts resolve per site: falak-db-<id> for containers on the database’s server, 127.0.0.1 and the host port for native sites there, and a shared private address for other servers of the environment (never public). ${{ secrets.NAME }} reads the secret store. See Variable references.