Get started with Neon Storage

To set up Neon Storage with an AI coding assistant, install the Neon Platform (neon) and Neon Storage skills:

npx skills add neondatabase/agent-skills -s neon -s neon-object-storage

To follow this guide, you need:

• Early access to the Neon Storage private preview
• A new Neon project in the AWS us-east-2 region
• The Neon CLI installed and authenticated if you use the recommended neon.ts flow
• A Neon API key in NEON_API_KEY if you use the manual API flow

Recommended: enable storage with neon.ts

The recommended way to enable storage and get credentials is via neon.ts, Neon's infrastructure-as-code config file. Install the config package, link your local app to the Neon project and branch you want to target, declare buckets under preview.buckets, then run neon deploy to provision them on the linked branch and pull credentials into .env.local automatically:

npm install @neon/config
neon link           # choose the project and branch for this app
neon branches list  # confirm the linked target branch before deploy

import { defineConfig } from '@neon/config/v1';

export default defineConfig({
  preview: {
    buckets: {
      'my-bucket': {},                          // private (default)
      'public-assets': { access: 'public_read' },
    },
  },
});

neon deploy          # provisions buckets and writes AWS_* vars to .env.local

After deploy, your .env.local contains AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, and AWS_REGION. Skip to Configure your client below.

Already deployed? Pull the vars again with:

neon env pull

If you prefer to manage credentials manually (for example, for CI or production deployments), follow the steps below. Replace {project_id} and {branch_id} in the API examples with your own IDs. You can find them in the Neon Console URL, or with neon projects list and neon branches list.

If you need a new branch, create it first, then wait until the branch is ready before calling Storage APIs. Branch creation is asynchronous, so a freshly-created branch can still be initializing even after the create request returns.

1. Find your branch endpoint

   Fetch your branch's storage state from the Neon API. Do this before creating credentials so you know the branch is ready for Storage calls. The response includes the full S3 endpoint URL, the region, and whether path-style addressing is required:

   curl "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/storage" \
     -H "Authorization: Bearer $NEON_API_KEY"

   {
     "enabled": true,
     "s3_endpoint": "https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.neon.tech",
     "region": "us-east-2",
     "force_path_style": true
   }

   Set these as environment variables:

   export AWS_ENDPOINT_URL_S3=https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.neon.tech
   export AWS_REGION=us-east-2

   A 404 response means Storage is not available for that branch. There is no separate manual enable API call: use the recommended neon.ts flow above, or make sure your project has Storage private preview access and is in the AWS us-east-2 region.

2. Create a credential

   Use the Neon API to create a credential with storage access:

   curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
     -H "Authorization: Bearer $NEON_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"scopes": ["storage:read", "storage:write"], "principal_type": "user"}'

   The response includes your S3 credentials. Store them immediately. You'll only get them once. See Authentication for how each field maps to your S3 client.

   {
     "token_id": "nak_live_...",
     "s3_secret_access_key": "nsk_live_...",
     ...
   }

   Set these as environment variables:

   export AWS_ACCESS_KEY_ID=nak_live_...   # token_id
   export AWS_SECRET_ACCESS_KEY=nsk_live_...   # s3_secret_access_key

3. Install dependencies

   Files SDKS3 ClientPython

   # files-sdk uses @aws-sdk/* packages as peer dependencies; install them alongside it
   npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @aws-sdk/s3-presigned-post dotenv

4. Configure your client

   The neon adapter is a subpath export (files-sdk/neon) that reads AWS_* environment variables and configures the Files SDK for Neon's S3-compatible endpoint automatically.

   Files SDKS3 ClientPythonAWS CLI

   import { Files } from 'files-sdk';
   import { neon } from 'files-sdk/neon';
   
   export const files = new Files({ adapter: neon({ bucket: 'my-bucket' }) });

   note

   If you're using Neon Functions, the AWS_* credentials are injected automatically when a bucket is declared in neon.ts. No .env setup is needed inside a function.

5. Create a bucket

   Create the bucket before uploading, or declare it in neon.ts and run neon deploy:

   neon buckets create my-bucket

   See Buckets for Neon API, S3 SDK, Python, and AWS CLI examples.

6. Upload a file

   Files SDKS3 ClientPythonAWS CLI

   import { files } from './client';
   
   await files.upload('hello.txt', 'Hello from Neon Storage!', {
     contentType: 'text/plain',
   });
   
   console.log('Uploaded!');

7. Download a file

   Files SDKS3 ClientPythonAWS CLI

   import { files } from './client';
   
   const result = await files.download('hello.txt');
   const text = await result.text();
   console.log(text); // Hello from Neon Storage!

Next steps

• Buckets: access levels, bucket branching, and the Console UI
• Objects: list, delete, multipart uploads, and presigned URLs
• Authentication: credential scopes, branch binding, and rotation
• with-files-sdk: working example showing how to upload files to a branch-scoped bucket using the Files SDK and its neon adapter