Create compute endpoint

POST/projects/{project_id}/endpointsCreate compute endpoint

Creates a compute endpoint for the specified branch. A compute endpoint is a Neon compute instance. There is a maximum of one read-write compute endpoint per branch. If the specified branch already has a read-write compute endpoint, the operation fails. A branch can have multiple read-only compute endpoints.

For more information about compute endpoints, see Manage computes.

Parameters

project_idstringpathrequired

The Neon project ID

pattern ^[a-z0-9-]{1,60}$

Request body

required

application/json

objectEndpointCreateRequest

endpointobjectrequired

Configuration for the compute endpoint to create.

Show child attributes

autoscaling_limit_max_cunumber

minimum 0.25

autoscaling_limit_min_cunumber

minimum 0.25

branch_idstringrequired

The ID of the branch the compute endpoint will be associated with

pattern ^[a-z0-9-]{1,60}$

disabledboolean

Whether to restrict connections to the compute endpoint. Enabling this option schedules a suspend compute operation. A disabled compute endpoint cannot be enabled by a connection or console action. However, the compute endpoint is periodically enabled by check_availability operations.

namestring

Optional name of the compute endpoint

maxLength 64 · minLength 1

passwordless_accessboolean

NOT YET IMPLEMENTED. Whether to permit passwordless access to the compute endpoint.

pooler_enabledboolean

Deprecated. To enable connection pooling, append `-pooler` to the endpoint ID in the connection string. See [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)

pooler_modestring

Deprecated. The connection pooler mode. Neon supports PgBouncer in `transaction` mode only. Removal scheduled for June 20, 2026.

one of "transaction"

provisionerstring

region_idstring

The region where the compute endpoint will be created. Only the project's `region_id` is permitted.

settingsobject

A collection of settings for a compute endpoint

Show child attributes

pg_settingsobject

A raw representation of Postgres settings

pgbouncer_settingsobject

Deprecated. A raw representation of PgBouncer settings. Removal scheduled for June 20, 2026.

preload_librariesobject

The shared libraries to preload into the project's compute instances.

Show child attributes

enabled_librariesarray of string

Names of shared preload libraries to enable for the project.

Show child attributes

use_defaultsboolean

When true, the project's preload libraries include the platform default set in addition to any libraries listed in `enabled_libraries`.

suspend_timeout_secondsinteger · int64

Duration of inactivity in seconds after which the compute endpoint is automatically suspended. The value `0` means use the default value. The value `-1` means never suspend. The default value is `300` seconds (5 minutes). The minimum value is `60` seconds (1 minute). The maximum value is `604800` seconds (1 week). For more information, see [Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).

maximum 604800 · minimum -1

typestringrequired

Compute endpoint type. `read_write`: the primary read-write endpoint (one per branch). `read_only`: a read replica endpoint (multiple allowed per branch).

one of "read_only", "read_write"

Example request

{
  "endpoint": {
    "branch_id": "br-floral-mountain-251143",
    "type": "read_write"
  }
}

Responses

valueEndpointOperations

allOf · 2 options

Option 1objectEndpointResponse

endpointobjectrequired

Show child attributes

autoscaling_limit_max_cunumberrequired

minimum 0.25

autoscaling_limit_min_cunumberrequired

minimum 0.25

branch_idstringrequired

The ID of the branch this compute endpoint belongs to.

pattern ^[a-z0-9-]{1,60}$

compute_release_versionstring

Attached compute's release version number.

created_atstring · date-timerequired

A timestamp indicating when the compute endpoint was created

creation_sourcestringrequired

The compute endpoint creation source

current_statestringrequired

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

disabledbooleanrequired

Whether to restrict connections to the compute endpoint. Enabling this option schedules a suspend compute operation. A disabled compute endpoint cannot be enabled by a connection or console action.

hoststringrequired

The hostname of the compute endpoint. This is the hostname specified when connecting to a Neon database.

idstringrequired

The compute endpoint ID. Compute endpoint IDs have an `ep-` prefix. For example: `ep-little-smoke-851426`

pattern ^[a-z0-9-]{1,60}$

last_activestring · date-time

A timestamp indicating when the compute endpoint was last active

namestring

Optional name of the compute endpoint

passwordless_accessbooleanrequired

Whether to permit passwordless access to the compute endpoint

pending_statestring

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

pooler_enabledbooleanrequired

Deprecated. To use connection pooling, append `-pooler` to the endpoint ID in the connection string.

pooler_modestringrequired

Deprecated. The connection pooler mode. Neon supports PgBouncer in `transaction` mode only. Removal scheduled for June 20, 2026.

one of "transaction"

project_idstringrequired

The ID of the project this compute endpoint belongs to.

pattern ^[a-z0-9-]{1,60}$

provisionerstringrequired

proxy_hoststringrequired

Deprecated. Use the `host` property instead.

region_idstringrequired

Cloud region where the resource's Postgres compute and storage reside (for example, `aws-us-east-1`). Valid values are returned by `GET /regions`.

settingsobjectrequiredEndpointSettingsData ↑

A collection of settings for a compute endpoint

started_atstring · date-time

A timestamp indicating when the compute endpoint was last started

suspend_timeout_secondsinteger · int64required

maximum 604800 · minimum -1

suspended_atstring · date-time

A timestamp indicating when the compute endpoint was last suspended

typestringrequired

Compute endpoint type. `read_write`: the primary read-write endpoint (one per branch). `read_only`: a read replica endpoint (multiple allowed per branch).

one of "read_only", "read_write"

updated_atstring · date-timerequired

A timestamp indicating when the compute endpoint was last updated

Option 2objectOperationsResponse

operationsarray of objectrequired

Show child attributes

Show array items

An asynchronous action Neon performs on your resources (for example, starting a compute or creating a branch). Fields such as `action`, `status`, and `total_duration_ms` describe the operation and its progress.

actionstringrequired

The action performed by the operation

one of "create_compute", "create_timeline", "start_compute", "suspend_compute", "apply_config", "check_availability", "delete_timeline", "create_branch", "import_data", "tenant_ignore", "tenant_attach", "tenant_detach", "tenant_detach_safekeepers", "tenant_attach_safekeepers", "tenant_reattach", "replace_safekeeper", "disable_maintenance", "apply_storage_config", "prepare_secondary_pageserver", "switch_pageserver", "detach_parent_branch", "timeline_archive", "timeline_unarchive", "start_reserved_compute", "sync_dbs_and_roles_from_compute", "apply_schema_from_branch", "timeline_mark_invisible", "timeline_update_protected_config", "prewarm_replica", "promote_replica", "set_storage_non_dirty", "swap_binding_id", "finalize_migration", "mark_migration_prepared", "update_catalog", "epc_sync"

branch_idstring

The ID of the branch this operation ran on.

pattern ^[a-z0-9-]{1,60}$

created_atstring · date-timerequired

A timestamp indicating when the operation was created

endpoint_idstring

The ID of the compute endpoint this operation ran on.

pattern ^[a-z0-9-]{1,60}$

errorstring

Human-readable message describing why the operation failed.

failures_countinteger · int32required

The number of times the operation failed

idstring · uuidrequired

The operation ID

project_idstringrequired

The ID of the project this operation ran on.

pattern ^[a-z0-9-]{1,60}$

retry_atstring · date-time

A timestamp indicating when the operation was last retried

statusstringrequired

Lifecycle state of the operation. `scheduling`: queued, not yet started. `running`: actively executing. `finished`: completed successfully. `failed`: ended with a failure. `error`: ended with a terminal error. `cancelling`: cancellation requested but not yet complete. `cancelled`: stopped before completion. `skipped`: bypassed without executing.

one of "scheduling", "running", "finished", "failed", "error", "cancelling", "cancelled", "skipped"

total_duration_msinteger · int32required

The total duration of the operation in milliseconds

updated_atstring · date-timerequired

A timestamp indicating when the operation status was last updated

Example response

{
  "endpoint": {
    "autoscaling_limit_max_cu": 1,
    "autoscaling_limit_min_cu": 1,
    "branch_id": "br-proud-paper-090813",
    "created_at": "2022-12-03T15:37:07Z",
    "creation_source": "console",
    "current_state": "init",
    "disabled": false,
    "host": "ep-shrill-thunder-454069.us-east-2.aws.neon.tech",
    "id": "ep-shrill-thunder-454069",
    "passwordless_access": true,
    "pending_state": "active",
    "pooler_enabled": false,
    "pooler_mode": "transaction",
    "project_id": "bitter-meadow-966132",
    "provisioner": "k8s-pod",
    "proxy_host": "us-east-2.aws.neon.tech",
    "region_id": "aws-us-east-2",
    "settings": {
      "pg_settings": {}
    },
    "suspend_timeout_seconds": 10800,
    "type": "read_write",
    "updated_at": "2022-12-03T15:37:07Z"
  },
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-proud-paper-090813",
      "created_at": "2022-12-03T15:37:07Z",
      "endpoint_id": "ep-shrill-thunder-454069",
      "failures_count": 0,
      "id": "874f8bfe-f51d-4c61-85af-a29bea73e0e2",
      "project_id": "bitter-meadow-966132",
      "status": "running",
      "total_duration_ms": 100,
      "updated_at": "2022-12-03T15:37:07Z"
    }
  ]
}

defaultGeneral Error. The request may or may not be safe to retry, depending on the HTTP method, response status code, and whether a response was received. - If no response is returned from the API, a network error or timeout likely occurred. - In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results. The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**. The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout. Any request that returns a `503 Service Unavailable` response is always safe to retry. Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress. application/json

objectGeneralError

codestringrequired

default ""

messagestringrequired

Error message

request_idstring

Unique identifier for the request, useful for debugging. You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.

Example response

{
  "code": "",
  "message": "string",
  "request_id": "string"
}

Examples

project_idrequiredpath parameter

curl -X POST 'https://console.neon.tech/api/v2/projects/string/endpoints' \
  -H 'Content-Type: application/json' \
  -d '{"endpoint":{"autoscaling_limit_max_cu":0,"autoscaling_limit_min_cu":0,"branch_id":"string","disabled":true,"name":"string","passwordless_access":true,"pooler_enabled":true,"pooler_mode":"transaction","provisioner":"k8s-neonvm","region_id":"string","settings":{"pg_settings":{"additionalProp1":"string"},"pgbouncer_settings":{"additionalProp1":"string"},"preload_libraries":{"enabled_libraries":["string"],"use_defaults":true}},"suspend_timeout_seconds":0,"type":"read_only"}}'

const response = await fetch('https://console.neon.tech/api/v2/projects/string/endpoints', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"endpoint":{"autoscaling_limit_max_cu":0,"autoscaling_limit_min_cu":0,"branch_id":"string","disabled":true,"name":"string","passwordless_access":true,"pooler_enabled":true,"pooler_mode":"transaction","provisioner":"k8s-neonvm","region_id":"string","settings":{"pg_settings":{"additionalProp1":"string"},"pgbouncer_settings":{"additionalProp1":"string"},"preload_libraries":{"enabled_libraries":["string"],"use_defaults":true}},"suspend_timeout_seconds":0,"type":"read_only"}}),
});
const data = await response.json();

const response = await fetch('https://console.neon.tech/api/v2/projects/string/endpoints', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"endpoint\":{\"autoscaling_limit_max_cu\":0,\"autoscaling_limit_min_cu\":0,\"branch_id\":\"string\",\"disabled\":true,\"name\":\"string\",\"passwordless_access\":true,\"pooler_enabled\":true,\"pooler_mode\":\"transaction\",\"provisioner\":\"k8s-neonvm\",\"region_id\":\"string\",\"settings\":{\"pg_settings\":{\"additionalProp1\":\"string\"},\"pgbouncer_settings\":{\"additionalProp1\":\"string\"},\"preload_libraries\":{\"enabled_libraries\":[\"string\"],\"use_defaults\":true}},\"suspend_timeout_seconds\":0,\"type\":\"read_only\"}}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://console.neon.tech/api/v2/projects/string/endpoints",
    headers={"Content-Type": "application/json"},
    data='{"endpoint":{"autoscaling_limit_max_cu":0,"autoscaling_limit_min_cu":0,"branch_id":"string","disabled":true,"name":"string","passwordless_access":true,"pooler_enabled":true,"pooler_mode":"transaction","provisioner":"k8s-neonvm","region_id":"string","settings":{"pg_settings":{"additionalProp1":"string"},"pgbouncer_settings":{"additionalProp1":"string"},"preload_libraries":{"enabled_libraries":["string"],"use_defaults":true}},"suspend_timeout_seconds":0,"type":"read_only"}}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"endpoint":{"autoscaling_limit_max_cu":0,"autoscaling_limit_min_cu":0,"branch_id":"string","disabled":true,"name":"string","passwordless_access":true,"pooler_enabled":true,"pooler_mode":"transaction","provisioner":"k8s-neonvm","region_id":"string","settings":{"pg_settings":{"additionalProp1":"string"},"pgbouncer_settings":{"additionalProp1":"string"},"preload_libraries":{"enabled_libraries":["string"],"use_defaults":true}},"suspend_timeout_seconds":0,"type":"read_only"}}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://console.neon.tech/api/v2/projects/string/endpoints", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://console.neon.tech/api/v2/projects/string/endpoints");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"endpoint\":{\"autoscaling_limit_max_cu\":0,\"autoscaling_limit_min_cu\":0,\"branch_id\":\"string\",\"disabled\":true,\"name\":\"string\",\"passwordless_access\":true,\"pooler_enabled\":true,\"pooler_mode\":\"transaction\",\"provisioner\":\"k8s-neonvm\",\"region_id\":\"string\",\"settings\":{\"pg_settings\":{\"additionalProp1\":\"string\"},\"pgbouncer_settings\":{\"additionalProp1\":\"string\"},\"preload_libraries\":{\"enabled_libraries\":[\"string\"],\"use_defaults\":true}},\"suspend_timeout_seconds\":0,\"type\":\"read_only\"}}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://console.neon.tech/api/v2/projects/string/endpoints"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"endpoint\":{\"autoscaling_limit_max_cu\":0,\"autoscaling_limit_min_cu\":0,\"branch_id\":\"string\",\"disabled\":true,\"name\":\"string\",\"passwordless_access\":true,\"pooler_enabled\":true,\"pooler_mode\":\"transaction\",\"provisioner\":\"k8s-neonvm\",\"region_id\":\"string\",\"settings\":{\"pg_settings\":{\"additionalProp1\":\"string\"},\"pgbouncer_settings\":{\"additionalProp1\":\"string\"},\"preload_libraries\":{\"enabled_libraries\":[\"string\"],\"use_defaults\":true}},\"suspend_timeout_seconds\":0,\"type\":\"read_only\"}}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://console.neon.tech/api/v2/projects/string/endpoints")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"endpoint\":{\"autoscaling_limit_max_cu\":0,\"autoscaling_limit_min_cu\":0,\"branch_id\":\"string\",\"disabled\":true,\"name\":\"string\",\"passwordless_access\":true,\"pooler_enabled\":true,\"pooler_mode\":\"transaction\",\"provisioner\":\"k8s-neonvm\",\"region_id\":\"string\",\"settings\":{\"pg_settings\":{\"additionalProp1\":\"string\"},\"pgbouncer_settings\":{\"additionalProp1\":\"string\"},\"preload_libraries\":{\"enabled_libraries\":[\"string\"],\"use_defaults\":true}},\"suspend_timeout_seconds\":0,\"type\":\"read_only\"}}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://console.neon.tech/api/v2/projects/string/endpoints");
request.Content = new StringContent("{\"endpoint\":{\"autoscaling_limit_max_cu\":0,\"autoscaling_limit_min_cu\":0,\"branch_id\":\"string\",\"disabled\":true,\"name\":\"string\",\"passwordless_access\":true,\"pooler_enabled\":true,\"pooler_mode\":\"transaction\",\"provisioner\":\"k8s-neonvm\",\"region_id\":\"string\",\"settings\":{\"pg_settings\":{\"additionalProp1\":\"string\"},\"pgbouncer_settings\":{\"additionalProp1\":\"string\"},\"preload_libraries\":{\"enabled_libraries\":[\"string\"],\"use_defaults\":true}},\"suspend_timeout_seconds\":0,\"type\":\"read_only\"}}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "endpoint": {
    "autoscaling_limit_max_cu": 1,
    "autoscaling_limit_min_cu": 1,
    "branch_id": "br-proud-paper-090813",
    "created_at": "2022-12-03T15:37:07Z",
    "creation_source": "console",
    "current_state": "init",
    "disabled": false,
    "host": "ep-shrill-thunder-454069.us-east-2.aws.neon.tech",
    "id": "ep-shrill-thunder-454069",
    "passwordless_access": true,
    "pending_state": "active",
    "pooler_enabled": false,
    "pooler_mode": "transaction",
    "project_id": "bitter-meadow-966132",
    "provisioner": "k8s-pod",
    "proxy_host": "us-east-2.aws.neon.tech",
    "region_id": "aws-us-east-2",
    "settings": {
      "pg_settings": {}
    },
    "suspend_timeout_seconds": 10800,
    "type": "read_write",
    "updated_at": "2022-12-03T15:37:07Z"
  },
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-proud-paper-090813",
      "created_at": "2022-12-03T15:37:07Z",
      "endpoint_id": "ep-shrill-thunder-454069",
      "failures_count": 0,
      "id": "874f8bfe-f51d-4c61-85af-a29bea73e0e2",
      "project_id": "bitter-meadow-966132",
      "status": "running",
      "total_duration_ms": 100,
      "updated_at": "2022-12-03T15:37:07Z"
    }
  ]
}

{
  "code": "",
  "message": "string",
  "request_id": "string"
}