# Projects

A project is a logical grouping of environments within an organization. For
example, a single organization might have a `billing` project and a `platform`
project, each with `production`, `staging`, and per-PR preview environments.

## Endpoints

### PUT /v1/organizations/{org}/projects/{project_id}

Create or update a project.

**Request body:**

```json
{ "region": "us-east", "postgres_major": 17 }
```

**Response `200 OK`:**

```json
{
  "organization_id": "acme",
  "project_id": "store",
  "region": "us-east",
  "postgres_major": 17,
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase project put acme store us-east
```

---

### GET /v1/organizations/{org}/projects/{project_id}

Read a project record.

**Response `200 OK`:**

```json
{
  "organization_id": "acme",
  "project_id": "store",
  "region": "us-east",
  "postgres_major": 17,
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Example:**

```sh
scribase project get acme store
```

---

## Regions

Regions identify where Scribase provisions managed Postgres environments. For
self-hosted deployments, the region is a label you define — it has no
infrastructure meaning beyond identifying which node or datacenter the
environment runs on.

Examples: `us-east`, `eu-1`, `ap-southeast-2`.

## Notes

- Project IDs follow the same rules as organization IDs: lowercase alphanumeric + hyphens, 2–64 characters.
- `postgres_major` must be `17` (the only supported version in the current release).
- A project cannot be deleted while it has active environments.