> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-sync-clickhouse-operator-docs-7e82242.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI

> Control your Managed Postgres services with our OpenAPI

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Private preview in ClickHouse Cloud'}
        </div>;
};

# Managed Postgres OpenAPI

Use the [ClickHouse OpenAPI](/products/cloud/features/admin-features/api) to programmatically
control your Managed Postgres services just like ClickHouse services. The
same API also exposes a [Prometheus endpoint] for scraping service metrics.
Already familiar with [OpenAPI]? Get your [API keys] and jump right to the
[Managed Postgres API reference][pg-openapi]. Otherwise, follow along for a
quick run-through.

<h2 id="api-keys">
  API Keys
</h2>

Using the ClickHouse OpenAPI requires authentication; see [API keys] for how
to create them. Then use them via basic auth credentials like so:

```bash theme={null}
KEY_ID=mykeyid
KEY_SECRET=mykeysecret

curl -s --user "$KEY_ID:$KEY_SECRET" https://api.clickhouse.cloud/v1/organizations | jq
```

<h2 id="organization-id">
  Organization ID
</h2>

Next you'll need your organization ID.

1. Select your organization name in the lower left corner of the console.
2. Select **Organization details**.
3. Hit the copy icon to the right of **Organization ID** to copy it directly
   to your clipboard.

<h2 id="crud">
  CRUD
</h2>

Let's explore the lifecycle of a Postgres service.

<h3 id="create">
  Create
</h3>

First, create a new one
using the [create API]. It requires the following properties in the JSON body
of the request:

* `name`: Name of the new Postgres service
* `provider`: Name of the cloud provider
* `region`: Region within the provider's network in which to deploy the
  service
* `size`: The VM size
* `storageSize`: The storage size for the VM

See the [create API] docs for the possible values for these properties. In
addition, let's specify Postgres 18 rather than the default, 17:

```bash theme={null}
create_data='{
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118
}'
```

Now use this data to create a new instance; note that it requires the content
type header:

```bash theme={null}
curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" \
    -d "$create_data" | jq
```

On success, it will create a new instance and return information about it,
including connection data:

```json theme={null}
{
  "result": {
    "id": "pg7myrd1j06p3gx4zrm2ze8qz6",
    "name": "my postgres",
    "provider": "aws",
    "region": "us-west-2",
    "postgresVersion": "18",
    "size": "r8gd.large",
    "storageSize": 118,
    "haType": "none",
    "tags": [],
    "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com:5432/postgres?channel_binding=require",
    "username": "postgres",
    "password": "vV6cfEr2p_-TzkCDrZOx",
    "hostname": "my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com",
    "isPrimary": true,
    "state": "creating"
  },
  "requestId": "a5957990-dbe5-46fd-b5ce-a7f8f79e50fe",
  "status": 200
}
```

<h3 id="read">
  Read
</h3>

Use the `id` from the response to fetch the service again:

```bash theme={null}
PG_ID=pg7myrd1j06p3gx4zrm2ze8qz6
curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq
```

The output will be similar to the JSON returned for creation, but keep an eye
on the `state`; when it changes to `running`, the server is ready:

```bash theme={null}
curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq .result.state
```

```json theme={null}
"running"
```

Now you can use the `connectionString` property to connect, for example via
[psql]:

```bash theme={null}
$ psql "$(
    curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq -r .result.connectionString
)"

psql (18.3)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
Type "help" for help.

postgres=# 
```

Type `\q` to exit [psql].

<h3 id="update">
  Update
</h3>

The [patch API] supports updating a subset of the properties of a Managed
Postgres service via [RFC 7396] JSON Merge Patch. Tags may be of particular
interest for complex deployments; simply send them alone in the request:

```bash theme={null}
curl -sX PATCH --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    -d '{"tags": [{"key": "Environment", "value": "production"}]}' \
    | jq .result
```

The returned data should include the new tags:

```json theme={null}
{
  "id": "$PG_ID",
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118,
  "haType": "none",
  "tags": [
    {
      "key": "Environment",
      "value": "production"
    }
  ],
  "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com:5432/postgres?channel_binding=require",
  "username": "postgres",
  "password": "vV6cfEr2p_-TzkCDrZOx",
  "hostname": "my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com",
  "isPrimary": true,
  "state": "running"
}
```

<h3 id="delete">
  Delete
</h3>

Use the [delete API] to delete a Postgres service.

<Warning>
  Deleting a Postgres service completely removes the service and all of its
  data. Be sure you have a backup or have promoted a replica to primary before
  deleting a service.
</Warning>

```bash theme={null}
curl -sX DELETE --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq
```

On success, the response will report status code 200, e.g.:

```json theme={null}
{
  "requestId": "ac9bbffa-e370-410c-8bdd-bd24bf3d7f82",
  "status": 200
}
```

<h2 id="monitoring">
  Monitoring
</h2>

Two Prometheus-compatible endpoints expose CPU, memory, I/O, connection,
and transaction metrics for Managed Postgres services: one returns
metrics for every service in the organization, the other for a single
service. See the [Prometheus endpoint] page for setup and the
[metrics reference] for the full list of metrics.

[ClickHouse OpenAPI]: /products/cloud/features/admin-features/api "Cloud API"

[OpenAPI]: https://www.openapis.org "OpenAPI Initiative"

[API keys]: /products/cloud/features/admin-features/api/openapi "Managing API Keys"

[Prometheus endpoint]: /products/managed-postgres/monitoring/prometheus "Managed Postgres Prometheus endpoint"

[metrics reference]: /products/managed-postgres/monitoring/metrics "Managed Postgres metrics reference"

[pg-openapi]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres "OpenAPI spec for ClickHouse Cloud: Postgres"

[list API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceGetList "Fetch a list of an organization's Postgres services"

[create API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceCreate "Create new Postgres service"

[psql]: https://www.postgresql.org/docs/current/app-psql.html "PostgreSQL Docs: psql — PostgreSQL interactive terminal"

[patch API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServicePatch "Update a PostgreSQL service"

[RFC 7396]: https://www.rfc-editor.org/rfc/rfc7396 "RFC 7396: JSON Merge Patch"

[Postgres configuration]: https://www.postgresql.org/docs/18/runtime-config.html "PostgreSQL Docs: Server Configuration"

[config API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceSetConfig "Update a Postgres Service configuration"

[delete API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceDelete "Delete a PostgreSQL service"