Neon Management API

openapi: 3.1.0
info:
  title: Neon Management API
  description: >-
    The Neon Management API is a RESTful interface for programmatically managing
    Neon serverless Postgres resources. It allows developers to create and manage
    projects, branches, databases, roles, compute endpoints, and operations. The
    API supports everything available through the Neon Console, enabling
    automation of database infrastructure workflows. An OpenAPI 3.0 specification
    is available along with TypeScript, Python, and Go SDKs.
  version: '2.0'
  contact:
    name: Neon Support
    url: https://neon.com/docs/introduction/support
  termsOfService: https://neon.com/terms-of-service
externalDocs:
  description: Neon API Documentation
  url: https://neon.com/docs/reference/api-reference
servers:
  - url: https://console.neon.tech/api/v2
    description: Neon Production API
tags:
  - name: API Keys
    description: >-
      Manage API keys for authentication. API keys are used to authenticate
      requests to the Neon API via Bearer token.
  - name: Auth
    description: >-
      Manage Neon Auth configuration for branches, including OAuth providers,
      webhooks, and authentication settings.
  - name: Branches
    description: >-
      Manage branches within a project. Branches are copies of your data
      created using copy-on-write technology for development, testing, and
      preview environments.
  - name: Consumption
    description: >-
      Query consumption metrics for projects and accounts. Available for
      Scale, Business, and Enterprise plan accounts.
  - name: Data API
    description: >-
      Manage Data API configuration for branches, including enabling and
      disabling the PostgREST-compatible HTTP interface.
  - name: Databases
    description: >-
      Manage databases within a branch. A branch can contain multiple databases.
  - name: Endpoints
    description: >-
      Manage compute endpoints for branches. Compute endpoints provide the
      processing resources for database queries. A branch can have one
      read-write and multiple read-only endpoints.
  - name: Operations
    description: >-
      View and manage operations for a project. Operations track the progress
      and status of actions performed on project resources.
  - name: Projects
    description: >-
      Manage Neon projects. A project is the top-level object in the Neon
      hierarchy containing branches, databases, roles, and compute endpoints.
  - name: Roles
    description: >-
      Manage Postgres roles within a branch. Roles control database access
      and permissions.
security:
  - bearerAuth: []
paths:
  /projects:
    get:
      operationId: listProjects
      summary: List projects
      description: >-
        Retrieves a list of projects for the authenticated user or organization.
        Returns project metadata including ID, name, region, creation time, and
        current status.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/cursorParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/orgIdParam'
      responses:
        '200':
          description: Successfully retrieved list of projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    post:
      operationId: createProject
      summary: Create a project
      description: >-
        Creates a new Neon project within an organization. You can specify a
        region and Postgres version in the request body. Neon currently supports
        PostgreSQL 14, 15, 16, and 17.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreateRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
                  connection_uris:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectionUri'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /projects/{project_id}:
    get:
      operationId: getProject
      summary: Retrieve project details
      description: >-
        Retrieves information about the specified project including its name,
        region, Postgres version, creation time, and current settings.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      responses:
        '200':
          description: Successfully retrieved project details
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    patch:
      operationId: updateProject
      summary: Update a project
      description: >-
        Updates the specified project. You can update the project name and
        other configurable settings.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectUpdateRequest'
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: >-
        Deletes the specified project and all its associated resources including
        branches, databases, roles, and compute endpoints.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      responses:
        '200':
          description: Project deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{project_id}/branches:
    get:
      operationId: listProjectBranches
      summary: List branches
      description: >-
        Retrieves a list of branches for the specified project. Returns branch
        metadata including ID, name, parent branch, creation time, and current
        state.
      tags:
        - Branches
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      responses:
        '200':
          description: Successfully retrieved list of branches
          content:
            application/json:
              schema:
                type: object
                properties:
                  branches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Branch'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    post:
      operationId: createProjectBranch
      summary: Create a branch
      description: >-
        Creates a branch in the specified project. You can specify a parent
        branch, endpoints, and other configuration. Branches use copy-on-write
        technology for instant creation.
      tags:
        - Branches
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BranchCreateRequest'
      responses:
        '201':
          description: Branch created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  branch:
                    $ref: '#/components/schemas/Branch'
                  endpoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
                  connection_uris:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectionUri'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{project_id}/branches/{branch_id}:
    get:
      operationId: getProjectBranch
      summary: Retrieve branch details
      description: >-
        Retrieves information about the specified branch including its name,
        parent branch, creation time, and current state.
      tags:
        - Branches
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Successfully retrieved branch details
          content:
            application/json:
              schema:
                type: object
                properties:
                  branch:
                    $ref: '#/components/schemas/Branch'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
    patch:
      operationId: updateProjectBranch
      summary: Update a branch
      description: >-
        Updates the specified branch. You can update the branch name and
        other configurable settings.
      tags:
        - Branches
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BranchUpdateRequest'
      responses:
        '200':
          description: Branch updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  branch:
                    $ref: '#/components/schemas/Branch'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
    delete:
      operationId: deleteProjectBranch
      summary: Delete a branch
      description: >-
        Deletes the specified branch and all its associated databases, roles,
        and compute endpoints.
      tags:
        - Branches
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Branch deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  branch:
                    $ref: '#/components/schemas/Branch'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
  /projects/{project_id}/branches/{branch_id}/restore:
    post:
      operationId: restoreProjectBranch
      summary: Restore a branch
      description: >-
        Restores a branch to a specified point in time or to another branch.
        This operation can be used for point-in-time recovery.
      tags:
        - Branches
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source_branch_id:
                  type: string
                  description: >-
                    The ID of the source branch to restore from.
                source_timestamp:
                  type: string
                  format: date-time
                  description: >-
                    The point in time to restore the branch to.
                preserve_under_name:
                  type: string
                  description: >-
                    Name to preserve the current branch state under before
                    restoring.
      responses:
        '200':
          description: Branch restore initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  branch:
                    $ref: '#/components/schemas/Branch'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
  /projects/{project_id}/branches/{branch_id}/databases:
    get:
      operationId: listProjectBranchDatabases
      summary: List databases
      description: >-
        Retrieves a list of databases for the specified branch. A branch can
        contain multiple databases.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Successfully retrieved list of databases
          content:
            application/json:
              schema:
                type: object
                properties:
                  databases:
                    type: array
                    items:
                      $ref: '#/components/schemas/Database'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
    post:
      operationId: createProjectBranchDatabase
      summary: Create a database
      description: >-
        Creates a database in the specified branch. You must specify a database
        name and owner role.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseCreateRequest'
      responses:
        '201':
          description: Database created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  database:
                    $ref: '#/components/schemas/Database'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
  /projects/{project_id}/branches/{branch_id}/databases/{database_name}:
    get:
      operationId: getProjectBranchDatabase
      summary: Retrieve database details
      description: >-
        Retrieves information about the specified database including its name,
        owner role, and creation time.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
        - $ref: '#/components/parameters/databaseNameParam'
      responses:
        '200':
          description: Successfully retrieved database details
          content:
            application/json:
              schema:
                type: object
                properties:
                  database:
                    $ref: '#/components/schemas/Database'
        '401':
          description: Unauthorized
        '404':
          description: Database not found
    patch:
      operationId: updateProjectBranchDatabase
      summary: Update a database
      description: >-
        Updates the specified database. You can update the database name and
        owner role.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
        - $ref: '#/components/parameters/databaseNameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseUpdateRequest'
      responses:
        '200':
          description: Database updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  database:
                    $ref: '#/components/schemas/Database'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Database not found
    delete:
      operationId: deleteProjectBranchDatabase
      summary: Delete a database
      description: >-
        Deletes the specified database from the branch.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
        - $ref: '#/components/parameters/databaseNameParam'
      responses:
        '200':
          description: Database deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  database:
                    $ref: '#/components/schemas/Database'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Database not found
  /projects/{project_id}/branches/{branch_id}/roles:
    get:
      operationId: listProjectBranchRoles
      summary: List roles
      description: >-
        Retrieves a list of Postgres roles for the specified branch.
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Successfully retrieved list of roles
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
    post:
      operationId: createProjectBranchRole
      summary: Create a role
      description: >-
        Creates a Postgres role in the specified branch. You must specify a
        role name.
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleCreateRequest'
      responses:
        '201':
          description: Role created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
  /projects/{project_id}/branches/{branch_id}/roles/{role_name}:
    get:
      operationId: getProjectBranchRole
      summary: Retrieve role details
      description: >-
        Retrieves information about the specified Postgres role.
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
        - $ref: '#/components/parameters/roleNameParam'
      responses:
        '200':
          description: Successfully retrieved role details
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
        '401':
          description: Unauthorized
        '404':
          description: Role not found
    delete:
      operationId: deleteProjectBranchRole
      summary: Delete a role
      description: >-
        Deletes the specified Postgres role from the branch.
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
        - $ref: '#/components/parameters/roleNameParam'
      responses:
        '200':
          description: Role deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Role not found
  /projects/{project_id}/branches/{branch_id}/roles/{role_name}/reset_password:
    post:
      operationId: resetProjectBranchRolePassword
      summary: Reset role password
      description: >-
        Resets the password for the specified Postgres role. Returns the new
        password in the response.
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/branchIdParam'
        - $ref: '#/components/parameters/roleNameParam'
      responses:
        '200':
          description: Password reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Role not found
  /projects/{project_id}/endpoints:
    get:
      operationId: listProjectEndpoints
      summary: List compute endpoints
      description: >-
        Retrieves a list of compute endpoints for the specified project.
        Returns endpoint metadata including ID, branch, type, host, and
        current state.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      responses:
        '200':
          description: Successfully retrieved list of endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/Endpoint'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    post:
      operationId: createProjectEndpoint
      summary: Create a compute endpoint
      description: >-
        Creates a compute endpoint for the specified branch. There is a maximum
        of one read-write compute endpoint per branch, while a branch can have
        multiple read-only compute endpoints.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndpointCreateRequest'
      responses:
        '201':
          description: Endpoint created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{project_id}/endpoints/{endpoint_id}:
    get:
      operationId: getProjectEndpoint
      summary: Retrieve compute endpoint details
      description: >-
        Retrieves information about the specified compute endpoint including
        its host, type, branch, autoscaling configuration, and current state.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/endpointIdParam'
      responses:
        '200':
          description: Successfully retrieved endpoint details
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
    patch:
      operationId: updateProjectEndpoint
      summary: Update a compute endpoint
      description: >-
        Updates the specified compute endpoint. You can update autoscaling
        settings, suspend timeout, and other configuration.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/endpointIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndpointUpdateRequest'
      responses:
        '200':
          description: Endpoint updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
    delete:
      operationId: deleteProjectEndpoint
      summary: Delete a compute endpoint
      description: >-
        Deletes the specified compute endpoint.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/endpointIdParam'
      responses:
        '200':
          description: Endpoint deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
  /projects/{project_id}/endpoints/{endpoint_id}/start:
    post:
      operationId: startProjectEndpoint
      summary: Start a compute endpoint
      description: >-
        Starts the specified compute endpoint. This operation resumes a
        suspended endpoint.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/endpointIdParam'
      responses:
        '200':
          description: Endpoint started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
  /projects/{project_id}/endpoints/{endpoint_id}/suspend:
    post:
      operationId: suspendProjectEndpoint
      summary: Suspend a compute endpoint
      description: >-
        Suspends the specified compute endpoint. A suspended endpoint does not
        consume compute resources.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/endpointIdParam'
      responses:
        '200':
          description: Endpoint suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
  /projects/{project_id}/endpoints/{endpoint_id}/restart:
    post:
      operationId: restartProjectEndpoint
      summary: Restart a compute endpoint
      description: >-
        Restarts the specified compute endpoint.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/projectIdParam'
        - $ref: '#/components/parameters/endpointIdParam'
      responses:
        '200':
          description: Endpoint restarted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/Endpoint'
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
  /projects/{project_id}/branches/{branch_id}/endpoints:
    get:
      operationId: listProjectBranchEndpoints
      summary: List branch endpoints
      description: >-
        Retrieves a list of compute endpoints for the specified branch.


# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/neon/refs/heads/main/openapi/neon-management-api-openapi.yml