Neon Endpoints API

openapi: 3.1.0
info:
  title: Neon Management API Keys Endpoints 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
servers:
- url: https://console.neon.tech/api/v2
  description: Neon Production API
security:
- bearerAuth: []
tags:
- 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.
paths:
  /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.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Successfully retrieved list of branch endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/Endpoint'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
components:
  parameters:
    projectIdParam:
      name: project_id
      in: path
      required: true
      description: The Neon project ID
      schema:
        type: string
    endpointIdParam:
      name: endpoint_id
      in: path
      required: true
      description: The compute endpoint ID
      schema:
        type: string
    branchIdParam:
      name: branch_id
      in: path
      required: true
      description: The branch ID
      schema:
        type: string
  schemas:
    EndpointUpdateRequest:
      type: object
      description: Request body for updating a compute endpoint
      properties:
        endpoint:
          type: object
          properties:
            autoscaling_limit_min_cu:
              type: number
              description: Minimum compute units for autoscaling
            autoscaling_limit_max_cu:
              type: number
              description: Maximum compute units for autoscaling
            suspend_timeout_seconds:
              type: integer
              description: Inactivity timeout in seconds
    EndpointCreateRequest:
      type: object
      description: Request body for creating a new compute endpoint
      properties:
        endpoint:
          type: object
          required:
          - branch_id
          - type
          properties:
            branch_id:
              type: string
              description: The branch ID to attach the endpoint to
            type:
              type: string
              enum:
              - read_write
              - read_only
              description: The endpoint type
            autoscaling_limit_min_cu:
              type: number
              description: Minimum compute units for autoscaling
            autoscaling_limit_max_cu:
              type: number
              description: Maximum compute units for autoscaling
            suspend_timeout_seconds:
              type: integer
              description: Inactivity timeout in seconds
    Endpoint:
      type: object
      description: A compute endpoint provides processing resources for database queries. Each branch can have one read-write and multiple read-only endpoints.
      properties:
        id:
          type: string
          description: The endpoint ID
        host:
          type: string
          description: The endpoint hostname
        project_id:
          type: string
          description: The project ID
        branch_id:
          type: string
          description: The branch ID
        region_id:
          type: string
          description: The region where the endpoint is deployed
        autoscaling_limit_min_cu:
          type: number
          description: Minimum compute units for autoscaling
        autoscaling_limit_max_cu:
          type: number
          description: Maximum compute units for autoscaling
        type:
          type: string
          enum:
          - read_write
          - read_only
          description: The endpoint type
        current_state:
          type: string
          enum:
          - init
          - active
          - idle
          description: The current state of the endpoint
        suspend_timeout_seconds:
          type: integer
          description: Seconds of inactivity before the endpoint is suspended
        provisioner:
          type: string
          description: The provisioner type
        created_at:
          type: string
          format: date-time
          description: Endpoint creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        disabled:
          type: boolean
          description: Whether the endpoint is disabled
    Operation:
      type: object
      description: An operation tracks the progress of an action performed on a project resource such as creating a branch, starting an endpoint, or updating a database.
      properties:
        id:
          type: string
          description: The operation ID
        project_id:
          type: string
          description: The project ID
        branch_id:
          type: string
          description: The branch ID associated with the operation
        endpoint_id:
          type: string
          description: The endpoint ID associated with the operation
        action:
          type: string
          description: The type of action being performed
          enum:
          - create_compute
          - create_timeline
          - start_compute
          - suspend_compute
          - apply_config
          - check_availability
          - delete_timeline
          - create_branch
          - tenant_ignore
          - tenant_attach
          - tenant_detach
          - replace_safekeeper
        status:
          type: string
          description: The current status of the operation
          enum:
          - scheduling
          - running
          - finished
          - failed
          - cancelling
          - cancelled
          - skipped
        failures_count:
          type: integer
          description: Number of times the operation has failed
        created_at:
          type: string
          format: date-time
          description: Operation creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last status update timestamp
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Neon API keys are used to authenticate requests. Include the API key in the Authorization header as a Bearer token.
externalDocs:
  description: Neon API Documentation
  url: https://neon.com/docs/reference/api-reference