---
title: "Create Postgres Cluster"
method: POST
path: "/postgres"
tags: ["Postgres Clusters"]
---

# Create Postgres Cluster

`POST /postgres`

Create a Managed Postgres cluster for the organization named in the request body. Provisioning is asynchronous, and a name is generated when one is not supplied.

## Request body

- CreatePostgresClusterRequest
  - `disk_size_gb` integer — Disk size in gigabytes.
  - `name` string — Name for the cluster. A name is generated when omitted.
  - `org_slug` string, required — Slug of the organization that will own the cluster.
  - `pg_major_version` '16' | '17' — Postgres major version.
  - `plan` 'basic' | 'starter' | 'launch' | 'scale' | 'Performance', required — Plan slug selecting CPU, memory, and disk sizing.
  - `pool_mode` 'session' | 'transaction' — Connection pooler mode.
  - `postgis_enabled` boolean — Enable PostGIS support, required to later enable PostGIS extensions.
  - `region` string, required — Fly region code where the cluster's primary runs.

## Response `201`

Cluster accepted for provisioning

- ShowPostgresClusterResponse
  - `data` PostgresCluster
    - `attached_apps` PostgresAttachedApp[] — Apps attached to the cluster.
      - `name` string — Attached Fly app name.
    - `cpu_kind` 'shared' | 'performance' — CPU class.
    - `cpus` integer — vCPUs per node.
    - `created_at` string — RFC 3339 creation timestamp.
    - `disk_size_gb` integer — Disk size in gigabytes.
    - `endpoints` PostgresClusterEndpoints
      - `primary` PostgresNodeEndpoints
        - `direct` PostgresEndpoint
          - `host` string — Hostname to connect to.
          - `port` integer — TCP port.
        - `pooler` PostgresEndpoint
          - `host` string — Hostname to connect to.
          - `port` integer — TCP port.
    - `id` string — Cluster ID.
    - `memory_mb` integer — Memory per node in megabytes.
    - `name` string — Cluster name.
    - `organization` OrganizationRef
      - `name` string — Organization name.
      - `slug` string — Organization slug.
    - `pg_major_version` '16' | '17' — Postgres major version.
    - `plan` 'basic' | 'starter' | 'launch' | 'scale' | 'Performance' — Plan slug.
    - `postgis_enabled` boolean — Whether PostGIS support is enabled.
    - `region` string — Fly region code.
    - `replicas` integer — Number of replicas.
    - `status` 'creating' | 'initializing' | 'ready' | 'deleting' | 'deleted' | 'failed' — Current lifecycle status.

## Other responses

- `400` — Creation failed
- `404` — Organization not found
- `422` — Invalid attributes

---

[API](https://skmtc.net/machines/apis/machines-api.md) · [All operations](https://skmtc.net/machines/apis/machines-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/machines/machines-api/versions/633ddedda749/schema)