### Manage Project Endpoints

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Examples of common endpoint operations including listing, creating, starting, and suspending endpoints within a project.

```python
# List all endpoints for a project
endpoints = client.endpoints(project_id="proj_123")

# Create a new endpoint
new_endpoint = client.endpoint_create(project_id="proj_123", type="read_write")

# Start an existing endpoint
client.endpoint_start(project_id="proj_123", endpoint_id="ep_456")

# Suspend an endpoint
client.endpoint_suspend(project_id="proj_123", endpoint_id="ep_456")
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Installs the necessary dependencies for developing the neon_api Python library using pip and a requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install neon_api Python Package

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Installs the neon_api Python package using pip. This is the primary method for adding the library to your Python environment.

```bash
pip install neon-api
```

--------------------------------

### Manage Neon API Keys with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Provides Python code examples for managing API keys using the neon_api wrapper. This includes listing, creating, and deleting API keys.

```python
# Returns a list of API keys.
api_keys_list = neon.api_keys()

# Creates an API key.
new_key = neon.api_key_create(**{"name": "my-key"})

# Deletes a given API key.
neon.api_key_delete(key_id='useo_xxxxxxxxxxxxxx')

```

--------------------------------

### Start Endpoint

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Starts a suspended endpoint by its ID within a project.

```APIDOC
## POST /projects/{project_id}/endpoints/{endpoint_id}/start

### Description
Start a suspended endpoint by its ID.

### Method
POST

### Endpoint
/projects/{project_id}/endpoints/{endpoint_id}/start

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **endpoint_id** (str) - Required - The ID of the endpoint to start.

### Response
#### Success Response (200)
- **message** (str) - A confirmation message indicating the endpoint has started.
```

--------------------------------

### Perform Neon API Operations

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Examples of common operations including retrieving user info, listing keys, creating keys, and revoking keys.

```python
from neon_api import NeonAPI

# Initialize the client.
neon = NeonAPI.from_environ() or NeonAPI(api_key='your_api_key')

# Get the current user
user = neon.me()
print(user)

# Get a list of API keys
keys = neon.api_keys()
print(keys)

# Create a new API key
new_key = neon.api_key_create(name="new_key")
print(new_key)

# Revoke an API key
revoked_key = neon.api_key_revoke(api_key_id="api_key_id_to_revoke")
print(revoked_key)
```

--------------------------------

### Get Neon Project Consumption Metrics

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Demonstrates how to retrieve project consumption metrics using the experimental `consumption()` method of the NeonAPI client.

```python
# Returns a list of project consumption metrics.
consumption_metrics = neon.consumption()

```

--------------------------------

### Manage Neon Databases with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Provides Python code examples for managing databases within a Neon project and branch using the neon_api wrapper. This includes listing, creating, updating, and deleting databases.

```python
# Returns a list of databases for a given project and branch.
databases_list = neon.databases(project_id='your_project_id', branch_id='your_branch_id')

# Returns a specific database.
database_info = neon.database(project_id='your_project_id', branch_id='your_branch_id', database_id='your_database_id')

# Creates a new database.
new_database = neon.database_create(project_id='your_project_id', branch_id='your_branch_id', **{"name": "new-database-name"})

# Updates a given database.
updated_database = neon.database_update(project_id='your_project_id', branch_id='your_branch_id', **{"name": "updated-database-name"})

# Deletes a given database.
neon.database_delete(project_id='your_project_id', branch_id='your_branch_id', database_id='your_database_id')

```

--------------------------------

### Get Project

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Retrieves details for a specific project.

```APIDOC
## GET /projects/{project_id}

### Description
Get details of a specific project.

### Method
GET

### Endpoint
/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

### Response
#### Success Response (200)
- **project** (Dict[str, Any]) - A dictionary representing the project.
```

--------------------------------

### Manage Neon Endpoints with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Demonstrates how to manage Neon endpoints using the neon_api Python wrapper. This includes creating, updating, deleting, starting, and suspending endpoints.

```python
# Returns a list of endpoints for a given project and branch.
 endpoints_list = neon.endpoints(project_id='your_project_id', branch_id='your_branch_id')

# Creates a new endpoint.
new_endpoint = neon.endpoint_create(project_id='your_project_id', branch_id='your_branch_id', **{"name": "new-endpoint-name"})

# Updates a given endpoint.
updated_endpoint = neon.endpoint_update(project_id='your_project_id', branch_id='your_branch_id', endpoint_id='your_endpoint_id', **{"name": "updated-endpoint-name"})

# Deletes a given endpoint.
neon.endpoint_delete(project_id='your_project_id', branch_id='your_branch_id', endpoint_id='your_endpoint_id')

# Starts a given endpoint.
neon.endpoint_start(project_id='your_project_id', branch_id='your_branch_id', endpoint_id='your_endpoint_id')

# Suspends a given endpoint.
neon.endpoint_suspend(project_id='your_project_id', branch_id='your_branch_id', endpoint_id='your_endpoint_id')

```

--------------------------------

### GET /projects

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Retrieves a list of all projects associated with the authenticated account.

```APIDOC
## GET /projects

### Description
Returns a list of all projects for the authenticated user.

### Method
GET

### Endpoint
/projects

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects containing project details.

#### Response Example
{
  "projects": [
    { "id": "project_123", "name": "my-project" }
  ]
}
```

--------------------------------

### Manage Neon Operations with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Provides Python code examples for managing operations within a Neon project using the neon_api wrapper. This includes listing and retrieving specific operations.

```python
# Returns a list of operations for a given project.
operations_list = neon.operations(project_id='your_project_id')

# Returns a specific operation.
operation_info = neon.operation(project_id='your_project_id', operation_id='your_operation_id')

```

--------------------------------

### Get Operation

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Retrieves details for a specific operation within a project.

```APIDOC
## GET /projects/{project_id}/operations/{operation_id}

### Description
Get details of a specific operation within a project.

### Method
GET

### Endpoint
/projects/{project_id}/operations/{operation_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **operation_id** (str) - Required - The ID of the operation.

### Response
#### Success Response (200)
- **operation** (Dict[str, Any]) - A dictionary representing the operation.
```

--------------------------------

### GET /projects/{project_id}/branches/{branch_id}/databases

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Lists all databases within a specific branch of a project.

```APIDOC
## GET /projects/{project_id}/branches/{branch_id}/databases

### Description
Retrieves a list of databases for a specific branch.

### Method
GET

### Endpoint
/projects/{project_id}/branches/{branch_id}/databases

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The project ID.
- **branch_id** (string) - Required - The branch ID.

### Response
#### Success Response (200)
- **databases** (array) - List of database objects.

#### Response Example
{
  "databases": [
    { "id": "db-1", "name": "main" }
  ]
}
```

--------------------------------

### Manage Compute Endpoints

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Covers lifecycle management for compute endpoints, including listing, creating, updating configurations, starting, suspending, and deleting endpoints.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

project_id = "project-id-here"

# List all endpoints in a project
endpoints = neon.endpoints(project_id)
for ep in endpoints.endpoints:
    print(f"Endpoint: {ep.id} (Host: {ep.host}, Status: {ep.current_state})")

# Get a specific endpoint
endpoint = neon.endpoint(project_id, endpoint_id="ep-xxx")
print(f"Endpoint host: {endpoint.endpoint.host}")

# Create a new endpoint
new_endpoint = neon.endpoint_create(
    project_id,
    endpoint={
        "branch_id": "br-xxx",
        "type": "read_write"
    }
)
print(f"Created endpoint: {new_endpoint.endpoint.id}")

# Update an endpoint (e.g., change compute size)
updated = neon.endpoint_update(
    project_id,
    endpoint_id="ep-xxx",
    endpoint={
        "autoscaling_limit_min_cu": 0.25,
        "autoscaling_limit_max_cu": 2
    }
)

# Start a suspended endpoint
neon.endpoint_start(project_id, endpoint_id="ep-xxx")

# Suspend an endpoint (to save costs)
neon.endpoint_suspend(project_id, endpoint_id="ep-xxx")

# Delete an endpoint
neon.endpoint_delete(project_id, endpoint_id="ep-xxx")
```

--------------------------------

### Get Endpoint

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Retrieves details for a specific endpoint within a project.

```APIDOC
## GET /projects/{project_id}/endpoints/{endpoint_id}

### Description
Get an endpoint for a given project and endpoint ID.

### Method
GET

### Endpoint
/projects/{project_id}/endpoints/{endpoint_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **endpoint_id** (str) - Required - The ID of the endpoint.

### Response
#### Success Response (200)
- **endpoint** (Dict[str, Any]) - A dictionary representing the endpoint.
```

--------------------------------

### Get Current User Info

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Retrieves information about the currently authenticated user.

```APIDOC
## GET /me

### Description
Get the current user's information.

### Method
GET

### Endpoint
/me

### Response
#### Success Response (200)
- **user_info** (Dict[str, Any]) - A dictionary containing the current user's details.
```

--------------------------------

### Initialize Neon API Client from Environment

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Demonstrates how to instantiate the Neon API client using the NEON_API_KEY stored in the system environment variables.

```python
from neon_api import NeonClient

# Initialize client using NEON_API_KEY from environment
client = NeonClient.from_environ()
```

--------------------------------

### Initialize Neon API Client

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Demonstrates how to set the API key environment variable and initialize the NeonAPI client in Python.

```bash
export NEON_API_KEY=your_api_key
```

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()
```

--------------------------------

### Initialize NeonAPI Client

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Demonstrates how to initialize the NeonAPI client with an API key. It also suggests using environment variables for better security.

```python
from neon_api import NeonAPI

# Initialize the client with an API key
neon = NeonAPI(api_key='your_api_key')

# Alternatively, initialize using an environment variable
# neon = NeonAPI.from_environ()
```

--------------------------------

### Initialize Neon API Client

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Initialize the client using an API key directly or via environment variables.

```python
from neon_api import NeonAPI

# Method 1: Direct initialization with API key
neon = NeonAPI(api_key='your_api_key')

# Method 2: Initialize from environment variable (recommended)
# First, set: export NEON_API_KEY=your_api_key
neon = NeonAPI.from_environ()

# Method 3: Using module-level convenience function
import neon_api
neon = neon_api.from_environ()
```

--------------------------------

### Manage Neon Projects with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Illustrates how to manage Neon projects using the neon_api Python wrapper. This covers retrieving, creating, updating, deleting projects, and managing their permissions.

```python
# Returns a list of projects.
projects_list = neon.projects()

# Returns a specific project.
project_info = neon.project(project_id='your_project_id')

# Creates a new project.
new_project = neon.project_create(project_id='new_project_id', **{"region": "aws-us-east-1"})

# Updates a given project.
updated_project = neon.project_update(project_id='your_project_id', **{"name": "updated-project-name"})

# Deletes a given project.
neon.project_delete(project_id='your_project_id')

# Returns a list of permissions for a given project.
permissions_list = neon.project_permissions(project_id='your_project_id')

# Grant permissions to a given project.
neon.project_permissions_grant(project_id='your_project_id', **{"role": "developer", "access": "read-write"})

# Revoke permissions from a given project.
neon.project_permissions_revoke(project_id='your_project_id', **{"role": "developer"})

# Returns the connection string for a given project.
connection_string = neon.connection_uri(project_id='your_project_id', database_name='your_db', role_name='your_role')

```

--------------------------------

### Manage API Keys

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

List, create, and revoke API keys for the Neon account.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

# List all API keys
keys = neon.api_keys()
for key in keys:
    print(f"Key ID: {key.id}, Name: {key.name}, Created: {key.created_at}")

# Create a new API key
new_key = neon.api_key_create(key_name="my-automation-key")
print(f"New key ID: {new_key.id}")
print(f"Key token (save this!): {new_key.key}")

# Revoke an API key
revoked = neon.api_key_revoke(api_key_id=new_key.id)
print(f"Key revoked: {revoked.revoked}")
```

--------------------------------

### Manage Project Permissions

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Shows how to list, grant, and revoke project-level permissions for team members using their email addresses.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

project_id = "project-id-here"

# List project permissions
permissions = neon.project_permissions(project_id)
for perm in permissions.project_permissions:
    print(f"Granted to: {perm.granted_to_email} at {perm.granted_at}")

# Grant permission to another user
neon.project_permissions_grant(
    project_id,
    email="colleague@company.com"
)

# Revoke permission from a user
neon.project_permissions_revoke(
    project_id,
    email="colleague@company.com"
)
```

--------------------------------

### Manage PostgreSQL Roles

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Demonstrates role management within a branch, including listing, creating, retrieving, password operations, and role deletion.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

project_id = "project-id-here"
branch_id = "br-xxx"

# List all roles in a branch
roles = neon.roles(project_id, branch_id)
for role in roles.roles:
    print(f"Role: {role.name} (Protected: {role.protected})")

# Get a specific role
role = neon.role(project_id, branch_id, role_name="myapp_user")
print(f"Role name: {role.role.name}")

# Create a new role
new_role = neon.role_create(project_id, branch_id, role_name="analytics_user")
print(f"Created role: {new_role.role.name}")

# Reveal a role's password
password = neon.role_password_reveal(project_id, branch_id, role_name="myapp_user")
print(f"Password: {password.password}")

# Reset a role's password
neon.role_password_reset(project_id, branch_id, role_name="myapp_user")

# Delete a role
neon.role_delete(project_id, branch_id, role_name="analytics_user")
```

--------------------------------

### Manage PostgreSQL Databases

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Provides methods to list, retrieve, create, update, and delete databases within a specific branch. Requires a valid project and branch ID.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

project_id = "project-id-here"
branch_id = "br-xxx"

# List all databases in a branch
databases = neon.databases(project_id, branch_id)
for db in databases.databases:
    print(f"Database: {db.name} (Owner: {db.owner_name})")

# Get a specific database
database = neon.database(project_id, branch_id, database_id="db-name")
print(f"Database: {database.database.name}")

# Create a new database
new_db = neon.database_create(
    project_id,
    branch_id,
    database={
        "name": "myapp_production",
        "owner_name": "neondb_owner"
    }
)
print(f"Created database: {new_db.database.name}")

# Update a database
updated = neon.database_update(
    project_id,
    branch_id,
    database_id="myapp_production",
    database={"name": "myapp_staging"}
)

# Delete a database
neon.database_delete(project_id, branch_id, database_id="myapp_staging")
```

--------------------------------

### Manage Neon Roles with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Shows how to manage roles within a Neon project and branch using the neon_api Python wrapper. This includes retrieving, creating, deleting, and resetting role passwords.

```python
# Returns a list of roles for a given project and branch.
roles_list = neon.roles(project_id='your_project_id', branch_id='your_branch_id')

# Returns a specific role.
role_info = neon.role(project_id='your_project_id', branch_id='your_branch_id', role_name='your_role_name')

# Creates a new role.
new_role = neon.role_create(project_id='your_project_id', branch_id='your_branch_id', role_name='new_role_name')

# Deletes a given role.
neon.role_delete(project_id='your_project_id', branch_id='your_branch_id', role_name='your_role_name')

# Reveals the password for a given role.
password = neon.role_password_reveal(project_id='your_project_id', branch_id='your_branch_id', role_name='your_role_name')

# Resets the password for a given role.
neon.role_password_reset(project_id='your_project_id', branch_id='your_branch_id', role_name='your_role_name')

```

--------------------------------

### Manage Neon Branches with neon_api

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Shows how to manage branches within a Neon project using the neon_api Python wrapper. This includes listing, creating, updating, deleting, and setting branches as primary.

```python
# Returns a list of branches for a given project.
branches_list = neon.branches(project_id='your_project_id')

# Returns a specific branch.
branch_info = neon.branch(project_id='your_project_id', branch_id='your_branch_id')

# Creates a new branch.
new_branch = neon.branch_create(project_id='your_project_id', **{"name": "new-branch-name"})

# Updates a given branch.
updated_branch = neon.branch_update(project_id='your_project_id', branch_id='your_branch_id', **{"name": "updated-branch-name"})

# Deletes a given branch.
neon.branch_delete(project_id='your_project_id', branch_id='your_branch_id')

# Sets a given branch as primary.
neon.branch_set_as_primary(project_id='your_project_id', branch_id='your_branch_id')

```

--------------------------------

### Retrieve Project Databases and Operations

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Methods for fetching lists of databases associated with a branch and retrieving project-level operations.

```python
# Get databases for a specific branch
databases = client.databases(project_id="proj_123", branch_id="br_789")

# Get project operations with pagination
ops = client.operations(project_id="proj_123", limit=10)
```

--------------------------------

### Manage Neon Database Branches

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Demonstrates how to delete a branch within a Neon project using the NeonAPI client.

```python
neon.branch_delete(project_id, branch_id="br-xxx")
```

--------------------------------

### Run Tests with Pytest-VCR

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Executes the project's test suite. It utilizes the `pytest-vcr` library for mocking HTTP requests, ensuring tests do not require an internet connection. New test cassettes can be recorded using `make record`.

```bash
$ make test
```

```bash
$ make record
```

--------------------------------

### List Databases

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Retrieves a list of databases for a specific project and branch, with support for pagination.

```APIDOC
## GET /projects/{project_id}/branches/{branch_id}/databases

### Description
Get a list of databases for a specific project and branch.

### Method
GET

### Endpoint
/projects/{project_id}/branches/{branch_id}/databases

### Query Parameters
- **cursor** (str) - Optional - The cursor for pagination.
- **limit** (int) - Optional - The maximum number of databases to retrieve.

### Response
#### Success Response (200)
- **databases** (List[Dict[str, Any]]) - A list of dictionaries, where each dictionary represents a database.
```

--------------------------------

### Database Management API

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

APIs for managing databases within a Neon project branch, including creation, deletion, and retrieval.

```APIDOC
## GET /projects/{project_id}/branches/{branch_id}/databases/{database_id}

### Description
Retrieve details of a specific database within a Neon project branch.

### Method
GET

### Endpoint
/projects/{project_id}/branches/{branch_id}/databases/{database_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch containing the database.
- **database_id** (str) - Required - The ID of the database to retrieve.

### Response
#### Success Response (200)
- **database** (dict) - A dictionary representing the database.

#### Response Example
```json
{
  "database": {
    "id": "db-xyz789abc",
    "project_id": "your_project_id",
    "branch_id": "br-abc123xyz",
    "name": "my_database",
    "created_at": "2023-10-27T11:00:00Z",
    "updated_at": "2023-10-27T11:00:00Z"
  }
}
```
```

```APIDOC
## POST /projects/{project_id}/branches/{branch_id}/databases

### Description
Create a new database within a specific Neon project branch.

### Method
POST

### Endpoint
/projects/{project_id}/branches/{branch_id}/databases

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch where the database will be created.

#### Request Body
- **json** (dict) - Required - The JSON payload for creating the database. Accepts all keyword arguments for the JSON body, typically including a `database_name` field.

### Response
#### Success Response (200)
- **database** (dict) - A dictionary representing the created database.

#### Response Example
```json
{
  "database": {
    "id": "db-xyz789abc",
    "project_id": "your_project_id",
    "branch_id": "br-abc123xyz",
    "name": "new_database_name",
    "created_at": "2023-10-27T11:05:00Z",
    "updated_at": "2023-10-27T11:05:00Z"
  }
}
```
```

```APIDOC
## DELETE /projects/{project_id}/branches/{branch_id}/databases/{database_id}

### Description
Delete a specific database from a Neon project branch.

### Method
DELETE

### Endpoint
/projects/{project_id}/branches/{branch_id}/databases/{database_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch containing the database.
- **database_id** (str) - Required - The ID of the database to delete.

### Response
#### Success Response (200)
- **database** (dict) - A dictionary representing the deleted database.

#### Response Example
```json
{
  "database": {
    "id": "db-xyz789abc",
    "project_id": "your_project_id",
    "branch_id": "br-abc123xyz",
    "name": "database_to_delete",
    "created_at": "2023-10-27T11:00:00Z",
    "updated_at": "2023-10-27T11:10:00Z"
  }
}
```
```

```APIDOC
## PATCH /projects/{project_id}/branches/{branch_id}/databases/{database_id}

### Description
Update an existing database within a Neon project branch.

### Method
PATCH

### Endpoint
/projects/{project_id}/branches/{branch_id}/databases/{database_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch containing the database.
- **database_id** (str) - Required - The ID of the database to update.

#### Request Body
- **json** (dict) - Optional - The JSON payload for updating the database. Accepts all keyword arguments for the JSON body.

### Response
#### Success Response (200)
- **database** (dict) - A dictionary representing the updated database.

#### Response Example
```json
{
  "database": {
    "id": "db-xyz789abc",
    "project_id": "your_project_id",
    "branch_id": "br-abc123xyz",
    "name": "renamed_database",
    "created_at": "2023-10-27T11:00:00Z",
    "updated_at": "2023-10-27T11:15:00Z"
  }
}
```
```

--------------------------------

### Implement Cursor-Based Pagination

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Shows how to iterate through paginated API results using a cursor. This pattern is essential for fetching large collections of projects, branches, or operations without hitting request limits.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

cursor = None
all_projects = []

while True:
    response = neon.projects(cursor=cursor, limit=10)
    all_projects.extend(response.projects)

    if hasattr(response, 'pagination') and response.pagination:
        cursor = response.pagination.cursor
    else:
        break

print(f"Total projects: {len(all_projects)}")
```

--------------------------------

### Project Management API

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

APIs for managing Neon projects, including creation, deletion, updates, and retrieval.

```APIDOC
## POST /projects

### Description
Create a new project.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **json** (dict) - Required - The JSON payload to send to the server.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **project** (Dict[str, Any]) - A dataclass representing the project.

#### Response Example
```json
{
  "example": "response body"
}
```

## DELETE /projects/{project_id}

### Description
Delete a project.

### Method
DELETE

### Endpoint
/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

### Response
#### Success Response (200)
- **project** (Dict[str, Any]) - A dataclass representing the project.

#### Response Example
```json
{
  "example": "response body"
}
```

## GET /projects/{project_id}/permissions

### Description
Get a project's permissions.

### Method
GET

### Endpoint
/projects/{project_id}/permissions

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

### Response
#### Success Response (200)
- **permissions** (Dict[str, Any]) - A dataclass representing the project permissions.

#### Response Example
```json
{
  "example": "response body"
}
```

## POST /projects/{project_id}/permissions/grant

### Description
Grant permissions to a project.

### Method
POST

### Endpoint
/projects/{project_id}/permissions/grant

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
#### Request Body
- **json** (dict) - Required - The JSON payload to send to the server.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **permissions** (Dict[str, Any]) - A dataclass representing the project permissions.

#### Response Example
```json
{
  "example": "response body"
}
```

## POST /projects/{project_id}/permissions/revoke

### Description
Revoke permissions from a project.

### Method
POST

### Endpoint
/projects/{project_id}/permissions/revoke

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
#### Request Body
- **json** (dict) - Required - The JSON payload to send to the server.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **permissions** (Dict[str, Any]) - A dataclass representing the project permissions.

#### Response Example
```json
{
  "example": "response body"
}
```

## PATCH /projects/{project_id}

### Description
Update a project.

### Method
PATCH

### Endpoint
/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
#### Request Body
- **json** (dict) - Required - The JSON payload to send to the server.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **project** (Dict[str, Any]) - A dataclass representing the project.

#### Response Example
```json
{
  "example": "response body"
}
```

## GET /projects

### Description
Get a list of projects. If shared is True, get a list of shared projects.

### Method
GET

### Endpoint
/projects

### Parameters
#### Query Parameters
- **shared** (bool) - Optional - Whether to retrieve shared projects (default is False).
- **cursor** (str) - Optional - The cursor for pagination (default is None).
- **limit** (int) - Optional - The maximum number of projects to retrieve (default is None).

### Response
#### Success Response (200)
- **projects** (List[Dict[str, Any]]) - A list of dataclasses representing the projects.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Role Management API

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

APIs for managing roles within Neon project branches.

```APIDOC
## GET /projects/{project_id}/branches/{branch_id}/roles/{role_name}

### Description
Get a role for a given branch.

### Method
GET

### Endpoint
/projects/{project_id}/branches/{branch_id}/roles/{role_name}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch.
- **role_name** (str) - Required - The name of the role.

### Response
#### Success Response (200)
- **role** (Dict[str, Any]) - A dataclass representing the role.

#### Response Example
```json
{
  "example": "response body"
}
```

## POST /projects/{project_id}/branches/{branch_id}/roles/{role_name}

### Description
Create a new role.

### Method
POST

### Endpoint
/projects/{project_id}/branches/{branch_id}/roles/{role_name}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch.
- **role_name** (str) - Required - The name of the role.
#### Request Body
- **json** (dict) - Required - The JSON payload to send to the server.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **role** (Dict[str, Any]) - A dataclass representing the role.

#### Response Example
```json
{
  "example": "response body"
}
```

## DELETE /projects/{project_id}/branches/{branch_id}/roles/{role_name}

### Description
Delete a role by given role name.

### Method
DELETE

### Endpoint
/projects/{project_id}/branches/{branch_id}/roles/{role_name}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch.
- **role_name** (str) - Required - The name of the role.

### Response
#### Success Response (200)
- **role** (Dict[str, Any]) - A dataclass representing the role.

#### Response Example
```json
{
  "example": "response body"
}
```

## POST /projects/{project_id}/branches/{branch_id}/roles/{role_name}/reset_password

### Description
Reset a role password.

### Method
POST

### Endpoint
/projects/{project_id}/branches/{branch_id}/roles/{role_name}/reset_password

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch.
- **role_name** (str) - Required - The name of the role.

### Response
#### Success Response (200)
- **role** (Dict[str, Any]) - A dataclass representing the role.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Handle API Errors with NeonAPIError

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Demonstrates how to wrap Neon API calls in a try-except block to catch and handle NeonAPIError exceptions. This ensures that failures, such as requesting non-existent resources, are managed gracefully.

```python
from neon_api import NeonAPI
from neon_api.exceptions import NeonAPIError

neon = NeonAPI.from_environ()

try:
    project = neon.project(project_id="non-existent-id")
except NeonAPIError as e:
    print(f"API Error: {e}")
```

--------------------------------

### Create Endpoint

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Creates a new endpoint within a project. Accepts a JSON payload for configuration.

```APIDOC
## POST /projects/{project_id}/endpoints

### Description
Create a new endpoint for a given project.

### Method
POST

### Endpoint
/projects/{project_id}/endpoints

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

#### Request Body
- **json** (dict) - Required - The JSON payload to send to the server for endpoint configuration.

### Response
#### Success Response (200)
- **endpoint** (Dict[str, Any]) - A dictionary representing the newly created endpoint.
```

--------------------------------

### Manage Database Branches

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Perform operations on branches, including listing, creating, updating, and setting primary branches.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()
project_id = "project-id-here"

# List all branches
branches = neon.branches(project_id)

# Create a new branch
new_branch = neon.branch_create(
    project_id,
    branch={
        "name": "feature-branch",
        "parent_id": "br-parent-id"
    }
)

# Set a branch as primary
neon.branch_set_as_primary(project_id, branch_id="br-xxx")
```

--------------------------------

### Generate Database Connection URI

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Retrieve a connection string for a specific database, with optional connection pooling.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

# Get connection URI for a project
conn = neon.connection_uri(
    project_id="project-id-here",
    database_name="neondb",
    role_name="neondb_owner",
    pooled=True
)

print(f"Connection URI: {conn.uri}")
```

--------------------------------

### Manage Neon Projects

Source: https://context7.com/neondatabase/neon-api-python/llms.txt

Perform CRUD operations on projects, which are the top-level containers for databases.

```python
from neon_api import NeonAPI

neon = NeonAPI.from_environ()

# List all projects
projects = neon.projects()
for project in projects.projects:
    print(f"Project: {project.name} (ID: {project.id})")

# Create a new project
new_project = neon.project_create(
    project={
        "name": "my-new-project",
        "region_id": "aws-us-east-2"
    }
)

# Update a project
updated = neon.project_update(
    project_id="project-id-here",
    project={"name": "renamed-project"}
)

# Delete a project
neon.project_delete(project_id="project-id-here")
```

--------------------------------

### List Roles for a Neon Branch

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

This function fetches a comprehensive list of all roles associated with a specific branch in a Neon project. It takes the project ID and branch ID as arguments and returns a list of role objects.

```python
from neon_api import NeonClient

client = NeonClient(api_key="YOUR_API_KEY")
roles_list = client.roles(project_id="prj_123", branch_id="br_456")
for role in roles_list:
    print(role)
```

--------------------------------

### Connection URI API

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

API to retrieve a connection URI for a Neon project.

```APIDOC
## GET /projects/{project_id}/connection-uri

### Description
Retrieve a connection URI for a specific Neon project.

### Method
GET

### Endpoint
/projects/{project_id}/connection-uri

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

#### Query Parameters
- **database_name** (str) - Optional - The name of the database to connect to. Defaults to the project's primary database.
- **role_name** (str) - Optional - The name of the role to use for the connection. Defaults to the project's primary role.
- **pooled** (bool) - Optional - Whether to return a pooled connection URI. Defaults to False.

### Response
#### Success Response (200)
- **connection_uri** (str) - The connection URI string.

#### Response Example
```json
{
  "connection_uri": "postgresql://user:password@ep-your-neon-host.region.aws.neon.tech:5432/main?sslmode=require"
}
```
```

--------------------------------

### List Endpoints

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

Retrieves a list of all endpoints for a given project.

```APIDOC
## GET /projects/{project_id}/endpoints

### Description
Get a list of endpoints for a given project.

### Method
GET

### Endpoint
/projects/{project_id}/endpoints

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

### Response
#### Success Response (200)
- **endpoints** (List[Dict[str, Any]]) - A list of dictionaries, where each dictionary represents an endpoint.
```

--------------------------------

### Branch Management API

Source: https://github.com/neondatabase/neon-api-python/blob/main/docs/index.md

APIs for managing branches within a Neon project, including creation, deletion, updating, and setting as primary.

```APIDOC
## POST /projects/{project_id}/branches

### Description
Create a new branch within a Neon project.

### Method
POST

### Endpoint
/projects/{project_id}/branches

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

#### Request Body
- **json** (dict) - Required - The JSON payload for creating the branch. Accepts all keyword arguments for the JSON body.

### Response
#### Success Response (200)
- **branch** (dict) - A dictionary representing the created branch.

#### Response Example
```json
{
  "branch": {
    "id": "br-abc123xyz",
    "project_id": "your_project_id",
    "name": "new_branch",
    "db_name": "main",
    "role_name": "primary",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z",
    "parent_timestamp": "2023-10-27T09:00:00Z"
  }
}
```
```

```APIDOC
## DELETE /projects/{project_id}/branches/{branch_id}

### Description
Delete a specific branch from a Neon project.

### Method
DELETE

### Endpoint
/projects/{project_id}/branches/{branch_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch to delete.

### Response
#### Success Response (200)
- **branch** (dict) - A dictionary representing the deleted branch.

#### Response Example
```json
{
  "branch": {
    "id": "br-abc123xyz",
    "project_id": "your_project_id",
    "name": "branch_to_delete",
    "db_name": "main",
    "role_name": "primary",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:05:00Z",
    "parent_timestamp": "2023-10-27T09:00:00Z"
  }
}
```
```

```APIDOC
## POST /projects/{project_id}/branches/{branch_id}/set-primary

### Description
Set a specific branch as the primary branch for a Neon project.

### Method
POST

### Endpoint
/projects/{project_id}/branches/{branch_id}/set-primary

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch to set as primary.

### Response
#### Success Response (200)
- **branch** (dict) - A dictionary representing the branch that was set as primary.

#### Response Example
```json
{
  "branch": {
    "id": "br-abc123xyz",
    "project_id": "your_project_id",
    "name": "new_primary_branch",
    "db_name": "main",
    "role_name": "primary",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:10:00Z",
    "parent_timestamp": "2023-10-27T09:00:00Z"
  }
}
```
```

```APIDOC
## PATCH /projects/{project_id}/branches/{branch_id}

### Description
Update an existing branch in a Neon project.

### Method
PATCH

### Endpoint
/projects/{project_id}/branches/{branch_id}

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.
- **branch_id** (str) - Required - The ID of the branch to update.

#### Request Body
- **json** (dict) - Optional - The JSON payload for updating the branch. Accepts all keyword arguments for the JSON body.

### Response
#### Success Response (200)
- **branch** (dict) - A dictionary representing the updated branch.

#### Response Example
```json
{
  "branch": {
    "id": "br-abc123xyz",
    "project_id": "your_project_id",
    "name": "updated_branch_name",
    "db_name": "main",
    "role_name": "primary",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:15:00Z",
    "parent_timestamp": "2023-10-27T09:00:00Z"
  }
}
```
```

```APIDOC
## GET /projects/{project_id}/branches

### Description
Retrieve a list of all branches for a given Neon project.

### Method
GET

### Endpoint
/projects/{project_id}/branches

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The ID of the project.

#### Query Parameters
- **cursor** (str) - Optional - The cursor for pagination. Defaults to None.
- **limit** (int) - Optional - The maximum number of branches to retrieve. Defaults to None.

### Response
#### Success Response (200)
- **branches** (list) - A list of dictionaries, where each dictionary represents a branch.

#### Response Example
```json
{
  "branches": [
    {
      "id": "br-abc123xyz",
      "project_id": "your_project_id",
      "name": "main",
      "db_name": "main",
      "role_name": "primary",
      "created_at": "2023-10-27T09:00:00Z",
      "updated_at": "2023-10-27T09:00:00Z",
      "parent_timestamp": null
    },
    {
      "id": "br-def456uvw",
      "project_id": "your_project_id",
      "name": "develop",
      "db_name": "main",
      "role_name": "user",
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:00:00Z",
      "parent_timestamp": "2023-10-27T09:00:00Z"
    }
  ]
}
```
```

--------------------------------

### POST /projects/{project_id}/branches

Source: https://github.com/neondatabase/neon-api-python/blob/main/README.md

Creates a new branch within a specified project.

```APIDOC
## POST /projects/{project_id}/branches

### Description
Creates a new branch for the specified project.

### Method
POST

### Endpoint
/projects/{project_id}/branches

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

#### Request Body
- **name** (string) - Required - The name of the new branch.

### Request Example
{
  "name": "dev-branch"
}

### Response
#### Success Response (200)
- **branch** (object) - The created branch details.

#### Response Example
{
  "id": "br-123",
  "name": "dev-branch"
}
```