# Projects API

> List, create, rename and delete Falak projects and environments through the REST API, and duplicate an environment's sites into a new environment.

Source: https://falak.sh/docs/api/projects/

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

```json
{"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`.

```bash
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.

```bash
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:

```json title="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](/docs/databases/redis-and-valkey/#create-an-instance) 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](/docs/api/sites/).

## Variable references

Site variables may contain `${{ <service>. }}`. 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](/docs/guides/variable-references/).