openapi: 3.1.0
info:
  title: Neon Management API Keys Projects 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: Projects
  description: Manage Neon projects. A project is the top-level object in the Neon hierarchy containing branches, databases, roles, and compute endpoints.
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}/connection_uri:
    get:
      operationId: getConnectionUri
      summary: Retrieve connection URI
      description: Retrieves the connection URI for the specified project. The connection URI includes the host, database, role, and password needed to connect.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - name: branch_id
        in: query
        description: The branch ID
        schema:
          type: string
      - name: endpoint_id
        in: query
        description: The endpoint ID
        schema:
          type: string
      - name: database_name
        in: query
        required: true
        description: The database name
        schema:
          type: string
      - name: role_name
        in: query
        required: true
        description: The role name
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved connection URI
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionUri'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
components:
  parameters:
    projectIdParam:
      name: project_id
      in: path
      required: true
      description: The Neon project ID
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      description: Maximum number of items to return per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    orgIdParam:
      name: org_id
      in: query
      description: The organization ID to scope the request to
      schema:
        type: string
    cursorParam:
      name: cursor
      in: query
      description: Pagination cursor for retrieving the next page of results
      schema:
        type: string
  schemas:
    Project:
      type: object
      description: A Neon project is the top-level object in the Neon hierarchy. It contains branches, databases, roles, and compute endpoints.
      properties:
        id:
          type: string
          description: The project ID
        platform_id:
          type: string
          description: The cloud platform ID
        region_id:
          type: string
          description: The region where the project is deployed
        name:
          type: string
          description: The project name
        provisioner:
          type: string
          enum:
          - k8s-pod
          - k8s-neonvm
          description: The provisioner type
        default_endpoint_settings:
          type: object
          description: Default settings for compute endpoints
          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: Seconds of inactivity before suspending the endpoint
        pg_version:
          type: integer
          description: The Postgres version (14, 15, 16, or 17)
          enum:
          - 14
          - 15
          - 16
          - 17
        store_passwords:
          type: boolean
          description: Whether connection passwords are stored
        active_time:
          type: integer
          description: Total active time in seconds
        cpu_used_sec:
          type: integer
          description: Total CPU seconds used
        maintenance_starts_at:
          type: string
          format: date-time
          description: Scheduled maintenance start time
        creation_source:
          type: string
          description: Source of project creation
        created_at:
          type: string
          format: date-time
          description: Project creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        org_id:
          type: string
          description: The organization ID this project belongs to
    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
    Pagination:
      type: object
      description: Pagination metadata for list responses
      properties:
        cursor:
          type: string
          description: Cursor value for the next page of results
        limit:
          type: integer
          description: Number of items per page
        sort_by:
          type: string
          description: Field used for sorting
        sort_order:
          type: string
          enum:
          - asc
          - desc
          description: Sort direction
    ProjectUpdateRequest:
      type: object
      description: Request body for updating a project
      properties:
        project:
          type: object
          properties:
            name:
              type: string
              description: The project name
              maxLength: 64
            default_endpoint_settings:
              type: object
              properties:
                autoscaling_limit_min_cu:
                  type: number
                  description: Minimum compute units
                autoscaling_limit_max_cu:
                  type: number
                  description: Maximum compute units
                suspend_timeout_seconds:
                  type: integer
                  description: Inactivity timeout in seconds
    ConnectionUri:
      type: object
      description: A database connection URI
      properties:
        connection_uri:
          type: string
          description: The full connection URI including host, database, role, and password
        connection_parameters:
          type: object
          description: Individual connection parameters
          properties:
            database:
              type: string
              description: The database name
            host:
              type: string
              description: The hostname
            password:
              type: string
              description: The password
            role:
              type: string
              description: The role name
    ProjectCreateRequest:
      type: object
      description: Request body for creating a new project
      properties:
        project:
          type: object
          properties:
            name:
              type: string
              description: The project name
              maxLength: 64
            region_id:
              type: string
              description: The region for the project. Available regions include aws-us-east-1, aws-us-east-2, aws-us-west-2, aws-eu-central-1, aws-ap-southeast-1.
            pg_version:
              type: integer
              description: The Postgres version
              enum:
              - 14
              - 15
              - 16
              - 17
            store_passwords:
              type: boolean
              description: Whether to store connection passwords
            default_endpoint_settings:
              type: object
              properties:
                autoscaling_limit_min_cu:
                  type: number
                  description: Minimum compute units
                autoscaling_limit_max_cu:
                  type: number
                  description: Maximum compute units
                suspend_timeout_seconds:
                  type: integer
                  description: Inactivity timeout in seconds
            org_id:
              type: string
              description: Organization ID for the project
  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