Neon

Run Neon serverless Postgres from a workflow: create and delete projects, branch a database for a preview or a test run and reset or roll it back, add databases and roles, and hand the next step a ready-to-use connection string.

Actions

Action	What it does
Create branch	Create a branch - an instant copy of another branch's data, for a preview deployment, a test run or a risky migration.
Create database	Create a database on a branch, owned by an existing role.
Create project	Create a Neon project, which comes with a default branch, a database, a role that owns it and a compute.
Create role	Create a Postgres role on a branch.
Delete branch	Delete a branch with its databases, roles and computes, and drop its connections.
Delete database	Delete a database from a branch, with all of its data on that branch.
Delete project	Delete a project and everything in it - every branch, database, role and compute - and drop its connections.
Get branch	Get one branch.
Get connection URI	Get a ready-to-use Postgres connection URI for a database and role, for a later step or an app to connect with.
Get operation	Check on one of the operations a change started - every create, delete, rename, reset and password reset returns them in 'operations'.
Get project	Get a project's settings and this billing period's usage - compute seconds, active seconds, storage, data written and data transferred - for a workflow that watches usage.
List branches	List a project's branches with their state, parent, size and which one is the default.
List computes	List a project's computes (IDs start with 'ep-'), with the branch each serves, its host and its state.
List databases	List the databases on a branch, with the role that owns each.
List organizations	List the Neon organizations this API key belongs to, with each one's ID, name and plan.
List projects	List the projects in an organization, with each one's ID, region, Postgres version and when its compute was last active.
List roles	List the Postgres roles on a branch.
Rename branch	Give a branch a new name.
Reset or restore branch	Replace a branch's data.
Reset role password	Give a role a new password, returned in 'role.password'.

Create branch

Create a branch - an instant copy of another branch's data, for a preview deployment, a test run or a risky migration. It gets its own compute unless you turn that off, and the result's 'connection_uri' (which contains a password) connects to it. The Free plan allows 10 branches per project.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branch namenametext: What to call the branch. Leave blank for a generated name.
Copy fromparent_idtext: The branch to copy. Leave blank for the project's default branch.
Branch as ofparent_timestampdate and time: Copy the data as it was at this moment instead of now. It has to be inside the project's history window - 6 hours on the Free plan.
Copyinit_sourcetext: Defaults to schema and data.One of: parent-data (Schema and data), parent-schema (Schema only, no data).
Add a computeadd_computetrue/false: Give the branch its own read-write compute, which it needs before anything can connect to it. On by default.Default: true.
Labelsannotation_valueobject: Up to 50 text labels to keep with the branch, such as the git commit or pull request it was made for.

Outputs

branchobject
connection_uritext: The first connection URI Neon returned, including the role's password.
connection_urislist
databaseslist
endpointslist
operationslist
roleslist

Example output

{
  "branch": {
    "active_time_seconds": 0,
    "compute_time_seconds": 0,
    "created_at": "2026-09-14T10:15:00Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1048576,
    "default": false,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "logical_size": 29360128,
    "name": "preview-pr-42",
    "parent_id": "br-wispy-dew-591433",
    "parent_timestamp": "2026-09-14T10:15:00Z",
    "project_id": "bold-cloud-468218",
    "protected": false,
    "state_changed_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "connection_uri": "postgresql://app_user:npg_ExamplePassword1@ep-cool-darkness-123456.us-east-2.aws.neon.tech/orders?sslmode=require",
  "connection_uris": [
    {
      "connection_parameters": {
        "database": "orders",
        "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
        "password": "npg_ExamplePassword1",
        "pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech",
        "role": "app_user"
      },
      "connection_uri": "postgresql://app_user:npg_ExamplePassword1@ep-cool-darkness-123456.us-east-2.aws.neon.tech/orders?sslmode=require"
    }
  ],
  "databases": [
    {
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "id": 834686,
      "name": "orders",
      "owner_name": "app_user",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 2,
      "autoscaling_limit_min_cu": 0.25,
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "creation_source": "console",
      "current_state": "idle",
      "disabled": false,
      "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "passwordless_access": true,
      "project_id": "bold-cloud-468218",
      "provisioner": "k8s-neonvm",
      "region_id": "aws-us-east-2",
      "settings": {},
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "roles": [
    {
      "authentication_method": "password",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "name": "app_user",
      "protected": false,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

Create database

Create a database on a branch, owned by an existing role. Create the role first with 'Create role' if it does not exist.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.
Database namenametextRequired: What to call the database.
Owner roleowner_nametextRequired: The role that will own the database.

Outputs

databaseobject
operationslist

Example output

{
  "database": {
    "branch_id": "br-aged-salad-637688",
    "created_at": "2026-09-14T10:15:00Z",
    "id": 834686,
    "name": "orders",
    "owner_name": "app_user",
    "updated_at": "2026-09-14T10:15:00Z"
  },
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

Create project

Create a Neon project, which comes with a default branch, a database, a role that owns it and a compute. The result includes 'connection_uri', a ready-to-use Postgres URL that contains the role's password. Neon finishes starting the project in the background, so the next step that changes it may wait a few seconds; that happens automatically.

Inputs

Organizationorg_idtextRequired: The organization the project will belong to.
Project namenametext: What to call the project. Leave blank and Neon uses the project's generated ID.
Regionregion_idtext: Where the database lives. Pick one of the regions this organization can use, or leave blank for Neon's default. It cannot be changed afterwards.
Postgres versionpg_versiontext: Leave blank for Neon's default, Postgres 18.One of: 18 (Postgres 18), 17 (Postgres 17), 16 (Postgres 16), 15 (Postgres 15), 14 (Postgres 14).
Default branch namebranch_nametext: Leave blank for 'main'.
Database namedatabase_nametext: Leave blank for 'neondb'.
Owner role namerole_nametext: The role that owns the database. Leave blank for '<database name>_owner'. At most 63 bytes.

Outputs

branchobject
connection_uritext: The first connection URI Neon returned, including the role's password.
connection_urislist
databaseslist
endpointslist
operationslist
projectobject
roleslist

Example output

{
  "branch": {
    "active_time_seconds": 12480,
    "compute_time_seconds": 3120,
    "created_at": "2026-08-02T08:00:00Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1048576,
    "default": true,
    "id": "br-wispy-dew-591433",
    "logical_size": 29360128,
    "name": "main",
    "project_id": "bold-cloud-468218",
    "protected": false,
    "state_changed_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "connection_uri": "postgresql://app_user:npg_ExamplePassword1@ep-cool-darkness-123456.us-east-2.aws.neon.tech/orders?sslmode=require",
  "connection_uris": [
    {
      "connection_parameters": {
        "database": "orders",
        "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
        "password": "npg_ExamplePassword1",
        "pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech",
        "role": "app_user"
      },
      "connection_uri": "postgresql://app_user:npg_ExamplePassword1@ep-cool-darkness-123456.us-east-2.aws.neon.tech/orders?sslmode=require"
    }
  ],
  "databases": [
    {
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "id": 834686,
      "name": "orders",
      "owner_name": "app_user",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 2,
      "autoscaling_limit_min_cu": 0.25,
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "creation_source": "console",
      "current_state": "idle",
      "disabled": false,
      "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "passwordless_access": true,
      "project_id": "bold-cloud-468218",
      "provisioner": "k8s-neonvm",
      "region_id": "aws-us-east-2",
      "settings": {},
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "project": {
    "active_time_seconds": 12480,
    "branch_logical_size_limit": 512,
    "branch_logical_size_limit_bytes": 536870912,
    "compute_time_seconds": 3120,
    "consumption_period_end": "2026-10-01T00:00:00Z",
    "consumption_period_start": "2026-09-01T00:00:00Z",
    "created_at": "2026-08-02T08:00:00Z",
    "creation_source": "console",
    "data_storage_bytes_hour": 40960,
    "data_transfer_bytes": 1048576,
    "history_retention_seconds": 21600,
    "id": "bold-cloud-468218",
    "name": "orders",
    "org_id": "org-morning-bread-81040908",
    "owner_id": "org-morning-bread-81040908",
    "pg_version": 18,
    "platform_id": "aws",
    "provisioner": "k8s-neonvm",
    "proxy_host": "us-east-2.aws.neon.tech",
    "region_id": "aws-us-east-2",
    "store_passwords": true,
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "roles": [
    {
      "authentication_method": "password",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "name": "app_user",
      "password": "npg_ExamplePassword1",
      "protected": false,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

Create role

Create a Postgres role on a branch. The result includes the new role's password in 'role.password' - the only time Neon returns it. Creating a role drops the connections to the branch's compute.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.
Role namenametextRequired: What to call the role. At most 63 bytes.
Cannot log inno_logintrue/false: Create a role that owns things or holds privileges but cannot be used to connect. Off by default.Default: false.

Outputs

operationslist
roleobject

Example output

{
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "role": {
    "authentication_method": "password",
    "branch_id": "br-aged-salad-637688",
    "created_at": "2026-09-14T10:15:00Z",
    "name": "app_user",
    "password": "npg_ExamplePassword1",
    "protected": false,
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Delete branch

Delete a branch with its databases, roles and computes, and drop its connections. Neon will not delete a project's default or root branch, or a branch that other branches were copied from. A branch that is already gone is reported as 'already_deleted' rather than as an error.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.

Outputs

branchobject
branch_idtext
operationslist
statustext: 'deleted', or 'already_deleted' if it was already gone.

Example output

{
  "branch": {
    "active_time_seconds": 0,
    "compute_time_seconds": 0,
    "created_at": "2026-09-14T10:15:00Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1048576,
    "default": false,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "logical_size": 29360128,
    "name": "preview-pr-42",
    "parent_id": "br-wispy-dew-591433",
    "parent_timestamp": "2026-09-14T10:15:00Z",
    "project_id": "bold-cloud-468218",
    "protected": false,
    "state_changed_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "branch_id": "br-aged-salad-637688",
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "status": "deleted"
}

Delete database

Delete a database from a branch, with all of its data on that branch. This cannot be undone. A database that is already gone is reported as 'already_deleted' rather than as an error.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.
Databasedatabase_nametextRequired: The database to delete.

Outputs

databaseobject
database_nametext
operationslist
statustext: 'deleted', or 'already_deleted' if it was already gone.

Example output

{
  "database": {
    "branch_id": "br-aged-salad-637688",
    "created_at": "2026-09-14T10:15:00Z",
    "id": 834686,
    "name": "orders",
    "owner_name": "app_user",
    "updated_at": "2026-09-14T10:15:00Z"
  },
  "database_name": "orders",
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "status": "deleted"
}

Delete project

Delete a project and everything in it - every branch, database, role and compute - and drop its connections. Neon can recover a deleted project for 7 days, but recovery is not an action here. Returns the project as it was.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.

Outputs

projectobject
statustext: 'deleted', or 'already_deleted' if it was already gone.

Example output

{
  "project": {
    "active_time_seconds": 12480,
    "branch_logical_size_limit": 512,
    "branch_logical_size_limit_bytes": 536870912,
    "compute_time_seconds": 3120,
    "consumption_period_end": "2026-10-01T00:00:00Z",
    "consumption_period_start": "2026-09-01T00:00:00Z",
    "created_at": "2026-08-02T08:00:00Z",
    "creation_source": "console",
    "data_storage_bytes_hour": 40960,
    "data_transfer_bytes": 1048576,
    "history_retention_seconds": 21600,
    "id": "bold-cloud-468218",
    "name": "orders",
    "org_id": "org-morning-bread-81040908",
    "owner_id": "org-morning-bread-81040908",
    "pg_version": 18,
    "platform_id": "aws",
    "provisioner": "k8s-neonvm",
    "proxy_host": "us-east-2.aws.neon.tech",
    "region_id": "aws-us-east-2",
    "store_passwords": true,
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "status": "deleted"
}

Get branch

Get one branch. Its 'current_state' is 'ready' once Neon has finished creating or resetting it, so a workflow can check this before using the branch.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.

Outputs

annotationobject
branchobject

Example output

{
  "annotation": {
    "object": {
      "id": "br-aged-salad-637688",
      "type": "console/branch"
    },
    "value": {
      "git-commit": "a1b2c3d"
    }
  },
  "branch": {
    "active_time_seconds": 0,
    "compute_time_seconds": 0,
    "created_at": "2026-09-14T10:15:00Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1048576,
    "default": false,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "logical_size": 29360128,
    "name": "preview-pr-42",
    "parent_id": "br-wispy-dew-591433",
    "parent_timestamp": "2026-09-14T10:15:00Z",
    "project_id": "bold-cloud-468218",
    "protected": false,
    "state_changed_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  }
}

Get connection URI

Get a ready-to-use Postgres connection URI for a database and role, for a later step or an app to connect with. The URI contains the role's password. The branch needs a read-write compute.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtext: The branch to connect to. Leave blank for the project's default branch.
Databasedatabase_nametextRequired: The database to connect to.
Rolerole_nametextRequired: The role to connect as.
Use connection poolingpooledtrue/false: Connect through Neon's connection pooler, for serverless code that opens many short connections. Off by default.Default: false.
Compute IDendpoint_idtext: A specific compute to connect through, such as 'ep-cool-darkness-123456' - a read replica, say. Leave blank for the branch's read-write compute.

Outputs

branch_idtext
database_nametext
endpoint_idtext
pooledtrue/false
project_idtext
role_nametext
uritext: The Postgres connection URI, including the password.

Example output

{
  "branch_id": "br-aged-salad-637688",
  "database_name": "orders",
  "endpoint_id": null,
  "pooled": false,
  "project_id": "bold-cloud-468218",
  "role_name": "app_user",
  "uri": "postgresql://app_user:npg_ExamplePassword1@ep-cool-darkness-123456.us-east-2.aws.neon.tech/orders?sslmode=require"
}

Get operation

Check on one of the operations a change started - every create, delete, rename, reset and password reset returns them in 'operations'. 'done' turns true when it has finished either way and 'succeeded' says which; Neon suggests checking about every 5 seconds.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Operation IDoperation_idtextRequired: The operation's ID, a UUID from an earlier step's 'operations' list, such as 'a07f8772-1877-4da9-a939-3a3ae62d1d8d'.

Outputs

donetrue/false: Whether the operation has finished, either way.
operationobject
succeededtrue/false: Whether it finished successfully.

Example output

{
  "done": true,
  "operation": {
    "action": "start_compute",
    "branch_id": "br-aged-salad-637688",
    "created_at": "2026-09-14T10:15:00Z",
    "endpoint_id": "ep-cool-darkness-123456",
    "failures_count": 0,
    "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
    "project_id": "bold-cloud-468218",
    "status": "finished",
    "total_duration_ms": 1480,
    "updated_at": "2026-09-14T10:15:00Z"
  },
  "succeeded": true
}

Get project

Get a project's settings and this billing period's usage - compute seconds, active seconds, storage, data written and data transferred - for a workflow that watches usage.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.

Outputs

projectobject

Example output

{
  "project": {
    "active_time_seconds": 12480,
    "branch_logical_size_limit": 512,
    "branch_logical_size_limit_bytes": 536870912,
    "compute_time_seconds": 3120,
    "consumption_period_end": "2026-10-01T00:00:00Z",
    "consumption_period_start": "2026-09-01T00:00:00Z",
    "created_at": "2026-08-02T08:00:00Z",
    "creation_source": "console",
    "data_storage_bytes_hour": 40960,
    "data_transfer_bytes": 1048576,
    "history_retention_seconds": 21600,
    "id": "bold-cloud-468218",
    "name": "orders",
    "org_id": "org-morning-bread-81040908",
    "owner_id": "org-morning-bread-81040908",
    "pg_version": 18,
    "platform_id": "aws",
    "provisioner": "k8s-neonvm",
    "proxy_host": "us-east-2.aws.neon.tech",
    "region_id": "aws-us-east-2",
    "store_passwords": true,
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  }
}

List branches

List a project's branches with their state, parent, size and which one is the default. Use it to find a branch's ID, or to tidy up old preview branches.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Searchsearchtext: Only branches whose name or ID contains this.
Sort bysort_bytext: Defaults to last updated.One of: updated_at (Last updated), created_at (Created), name.
Ordersort_ordertext: Defaults to descending - newest first.One of: desc (Descending), asc (Ascending).
How manylimitnumber: How many branches to return, 1-1000. Leave blank for every branch.From 1 to 1000.
Next pagecursortext: To get the next page of branches, paste 'next_cursor' from the previous result here. Leave blank for the first page.

Outputs

annotationsobject
brancheslist
countnumber: How many records this result holds.
has_moretrue/false: Whether another page follows.
next_cursortext: Pass this as 'Next page' to get the next page, or null.

Example output

{
  "annotations": {},
  "branches": [
    {
      "active_time_seconds": 12480,
      "compute_time_seconds": 3120,
      "created_at": "2026-08-02T08:00:00Z",
      "creation_source": "console",
      "current_state": "ready",
      "data_transfer_bytes": 1048576,
      "default": true,
      "id": "br-wispy-dew-591433",
      "logical_size": 29360128,
      "name": "main",
      "project_id": "bold-cloud-468218",
      "protected": false,
      "state_changed_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z",
      "written_data_bytes": 2097152
    },
    {
      "active_time_seconds": 0,
      "compute_time_seconds": 0,
      "created_at": "2026-09-14T10:15:00Z",
      "creation_source": "console",
      "current_state": "ready",
      "data_transfer_bytes": 1048576,
      "default": false,
      "id": "br-aged-salad-637688",
      "init_source": "parent-data",
      "logical_size": 29360128,
      "name": "preview-pr-42",
      "parent_id": "br-wispy-dew-591433",
      "parent_timestamp": "2026-09-14T10:15:00Z",
      "project_id": "bold-cloud-468218",
      "protected": false,
      "state_changed_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z",
      "written_data_bytes": 2097152
    }
  ],
  "count": 2,
  "has_more": false,
  "next_cursor": null
}

List computes

List a project's computes (IDs start with 'ep-'), with the branch each serves, its host and its state. 'idle' means scaled to zero, which is normal - it wakes on the next connection.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtext: Only the computes of this branch. Leave blank for all.

Outputs

branch_idtext
countnumber: How many records this result holds.
endpointslist

Example output

{
  "branch_id": null,
  "count": 1,
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 2,
      "autoscaling_limit_min_cu": 0.25,
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "creation_source": "console",
      "current_state": "idle",
      "disabled": false,
      "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "passwordless_access": true,
      "project_id": "bold-cloud-468218",
      "provisioner": "k8s-neonvm",
      "region_id": "aws-us-east-2",
      "settings": {},
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

List databases

List the databases on a branch, with the role that owns each.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.

Outputs

branch_idtext
countnumber: How many records this result holds.
databaseslist

Example output

{
  "branch_id": "br-aged-salad-637688",
  "count": 1,
  "databases": [
    {
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "id": 834686,
      "name": "orders",
      "owner_name": "app_user",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

List organizations

List the Neon organizations this API key belongs to, with each one's ID, name and plan. Every Neon project belongs to an organization, and listing or creating projects asks for one. With an organization or project-scoped key it returns the one organization that owns the key.

Inputs

None.

Outputs

countnumber: How many records this result holds.
organizationslist

Example output

{
  "count": 1,
  "organizations": [
    {
      "created_at": "2026-01-10T09:00:00Z",
      "handle": "acme",
      "id": "org-morning-bread-81040908",
      "managed_by": "console",
      "name": "Acme",
      "plan": "free",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

List projects

List the projects in an organization, with each one's ID, region, Postgres version and when its compute was last active. Projects Neon could not read in time are named in 'unavailable_project_ids' rather than silently left out.

Inputs

Organizationorg_idtextRequired: The organization whose projects to list.
Searchsearchtext: Only projects whose name or ID contains this.
How manylimitnumber: How many projects to return, 1-400. Defaults to 50.From 1 to 400.
Next pagecursortext: To get the next page of projects, paste 'next_cursor' from the previous result here. Leave blank for the first page.

Outputs

countnumber: How many records this result holds.
has_moretrue/false: Whether another page may follow - true when this page is full.
next_cursortext: Pass this as 'Next page' to get the next page, or null.
org_idtext
projectslist
unavailable_project_idslist

Example output

{
  "count": 1,
  "has_more": false,
  "next_cursor": null,
  "org_id": "org-morning-bread-81040908",
  "projects": [
    {
      "active_time_seconds": 12480,
      "branch_logical_size_limit": 512,
      "branch_logical_size_limit_bytes": 536870912,
      "compute_time_seconds": 3120,
      "consumption_period_end": "2026-10-01T00:00:00Z",
      "consumption_period_start": "2026-09-01T00:00:00Z",
      "created_at": "2026-08-02T08:00:00Z",
      "creation_source": "console",
      "data_storage_bytes_hour": 40960,
      "data_transfer_bytes": 1048576,
      "history_retention_seconds": 21600,
      "id": "bold-cloud-468218",
      "name": "orders",
      "org_id": "org-morning-bread-81040908",
      "owner_id": "org-morning-bread-81040908",
      "pg_version": 18,
      "platform_id": "aws",
      "provisioner": "k8s-neonvm",
      "proxy_host": "us-east-2.aws.neon.tech",
      "region_id": "aws-us-east-2",
      "store_passwords": true,
      "updated_at": "2026-09-14T10:15:00Z",
      "written_data_bytes": 2097152
    }
  ],
  "unavailable_project_ids": []
}

List roles

List the Postgres roles on a branch. Passwords are never included - Neon returns one only when a role is created or its password is reset.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.

Outputs

branch_idtext
countnumber: How many records this result holds.
roleslist

Example output

{
  "branch_id": "br-aged-salad-637688",
  "count": 1,
  "roles": [
    {
      "authentication_method": "password",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "name": "app_user",
      "protected": false,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ]
}

Rename branch

Give a branch a new name. Its ID and data stay the same.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.
New namenametextRequired: The branch's new name.

Outputs

branchobject
operationslist
source_branch_idtext: The branch the data was restored from.

Example output

{
  "branch": {
    "active_time_seconds": 0,
    "compute_time_seconds": 0,
    "created_at": "2026-09-14T10:15:00Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1048576,
    "default": false,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "logical_size": 29360128,
    "name": "preview-pr-42-renamed",
    "parent_id": "br-wispy-dew-591433",
    "parent_timestamp": "2026-09-14T10:15:00Z",
    "project_id": "bold-cloud-468218",
    "protected": false,
    "state_changed_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "operations": []
}

Reset or restore branch

Replace a branch's data. Leave 'Restore from' blank to reset the branch to its parent's latest data - the usual way to refresh a preview branch. Or pick the branch itself with 'As of' to roll it back to an earlier moment, which needs 'Keep current state as'. The branch's current data is replaced and its connections drop.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch whose data is replaced.
Restore fromsource_branch_idtext: The branch to take the data from. Leave blank for this branch's parent.
As ofsource_timestampdate and time: Take the data as it was at this moment rather than now. Required when restoring a branch from itself; it has to be inside the history window - 6 hours on the Free plan.
LSNsource_lsntext: Instead of 'As of', an exact Postgres log position such as 0/1A2B3C4. Use one or the other.
Keep current state aspreserve_under_nametext: Save the branch as it is now under this name before restoring. Required when restoring a branch from itself or when other branches were copied from it.

Outputs

branchobject
operationslist
source_branch_idtext: The branch the data was restored from.

Example output

{
  "branch": {
    "active_time_seconds": 0,
    "compute_time_seconds": 0,
    "created_at": "2026-09-14T10:15:00Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1048576,
    "default": false,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "last_reset_at": "2026-09-14T10:15:00Z",
    "logical_size": 29360128,
    "name": "preview-pr-42",
    "parent_id": "br-wispy-dew-591433",
    "parent_timestamp": "2026-09-14T10:15:00Z",
    "project_id": "bold-cloud-468218",
    "protected": false,
    "state_changed_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "written_data_bytes": 2097152
  },
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "source_branch_id": "br-wispy-dew-591433"
}

Reset role password

Give a role a new password, returned in 'role.password'. The old password keeps working until Neon's operation finishes, and connections to the branch's compute drop.

Inputs

Projectproject_idtextRequired: The Neon project. Pick one from the list, or paste a project ID such as 'bold-cloud-468218' or the project's Neon Console URL.
Branchbranch_idtextRequired: The branch. Pick one from the project's branches, or paste a branch ID such as 'br-aged-salad-637688' or its Neon Console URL.
Rolerole_nametextRequired: The role whose password to reset.

Outputs

operationslist
roleobject

Example output

{
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-aged-salad-637688",
      "created_at": "2026-09-14T10:15:00Z",
      "endpoint_id": "ep-cool-darkness-123456",
      "failures_count": 0,
      "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d",
      "project_id": "bold-cloud-468218",
      "status": "running",
      "total_duration_ms": 1480,
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "role": {
    "authentication_method": "password",
    "branch_id": "br-aged-salad-637688",
    "created_at": "2026-09-14T10:15:00Z",
    "name": "app_user",
    "password": "npg_ExamplePassword1",
    "protected": false,
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

ActionsCopy Anchor Link

Create branchCopy Anchor Link

Inputs

Outputs

Create databaseCopy Anchor Link

Inputs

Outputs

Create projectCopy Anchor Link

Inputs

Outputs

Create roleCopy Anchor Link

Inputs

Outputs

Delete branchCopy Anchor Link

Inputs

Outputs

Delete databaseCopy Anchor Link

Inputs

Outputs

Delete projectCopy Anchor Link

Inputs

Outputs

Get branchCopy Anchor Link

Inputs

Outputs

Get connection URICopy Anchor Link

Inputs

Outputs

Get operationCopy Anchor Link

Inputs

Outputs

Get projectCopy Anchor Link

Inputs

Outputs

List branchesCopy Anchor Link

Inputs

Outputs

List computesCopy Anchor Link

Inputs

Outputs

List databasesCopy Anchor Link

Inputs

Outputs

List organizationsCopy Anchor Link

Inputs

Outputs

List projectsCopy Anchor Link

Inputs

Outputs

List rolesCopy Anchor Link

Inputs

Outputs

Rename branchCopy Anchor Link

Inputs

Outputs

Reset or restore branchCopy Anchor Link

Inputs

Outputs

Reset role passwordCopy Anchor Link

Inputs

Outputs

On this page

Actions

Create branch

Create database

Create project

Create role

Delete branch

Delete database

Delete project

Get branch

Get connection URI

Get operation

Get project

List branches

List computes

List databases

List organizations

List projects

List roles

Rename branch

Reset or restore branch

Reset role password