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.

The project resource

{"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

List projects, or show one with its environments.

POST /api/v1/projects — projects.manage

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

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

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

The project’s environments.

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.

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

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

The canvas’ + Create. For a database:

Request body — Redis / Valkey

{"kind": "database", "engine": "redis", "server_id": "01k…", "name": "cache",
 "maxmemory_mb": 128, "eviction": "noeviction", "persistence": "rdb"}

engine is postgresql, mysql, mariadb, redis or valkey. The server must already run that engine. maxmemory_mb, eviction and persistence only apply to redis/valkey (see Redis and Valkey for their defaults and allowed values); a Redis/Valkey instance also gets its own port (6380–6479) and password, and needs an agent that reports the db.redis feature (422 Update the agent on <server> first otherwise).

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 agent confirms it.

Placing sites

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.

Variable references

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 — REDIS_HOST/REDIS_URL resolve per site: 127.0.0.1 on the instance’s server, the Docker bridge for containers there, and a shared private address for other servers of the environment (never public; needs agent v0.7.1). See Variable references.