Storage Providers

Storage provider endpoints let you configure where NekoHub stores uploaded assets. You can maintain multiple profiles and designate one as the default. All endpoints require authentication via JWT Bearer token or API key. Supported provider types:

local — local filesystem storage
s3 — S3-compatible object storage (AWS S3, MinIO, R2, etc.)
github-repo — GitHub repository storage

Get storage providers overview

GET /api/v1/system/storage/providers

Returns all configured storage profiles, the active default profile, and runtime information about the currently active storage backend. Required permission: providers.read

Response

object

Show properties

array

All configured storage profiles.

Show profile properties

string (uuid)

Profile ID.

string

Unique internal name for the profile.

string

Human-readable display name.

string

Provider type: local, s3, or github-repo.

boolean

Whether this profile is enabled.

boolean

Whether this is the default profile for new uploads.

object

What this provider supports.

Show properties

boolean

Can serve files publicly.

boolean

Can serve files privately.

boolean

Can change file visibility after upload.

boolean

Can delete files.

boolean

Can generate direct public URLs.

boolean

Whether access must go through the NekoHub proxy.

boolean

Whether this provider is recommended as primary storage.

boolean

Whether backed by an external platform.

boolean

Whether this provider is experimental.

boolean

Whether a token is needed for private reads.

object

Non-sensitive configuration summary (root path, bucket, endpoint host, etc.).

string (ISO 8601)

Creation timestamp.

string (ISO 8601)

Last update timestamp.

object

The profile currently marked as default, or null.

object

The effective profile used for writes, or null.

object

Information about the currently active runtime storage backend.

Show properties

string

Active provider type.

string

Active provider name.

object

Capabilities of the active runtime provider.

boolean

Whether the runtime is driven by the database profile configuration.

boolean

Whether the runtime provider type matches the default profile.

object

Runtime and profile alignment status.

Show properties

string

How the runtime was selected.

boolean

Whether a default profile is configured.

boolean

Whether the default profile is enabled.

boolean

Whether the runtime and default profile types match.

string

Alignment status code.

string

Human-readable alignment status message.

Example

curl http://localhost:5121/api/v1/system/storage/providers \
  -H "Authorization: Bearer <token>"

Create a storage profile

POST /api/v1/system/storage/providers

Creates a new storage provider profile. Required permission: providers.create

Request body

string

required

Unique internal name for the profile (e.g. my-s3-bucket).

string

required

Human-readable name shown in the UI.

string

required

Provider type. One of: local, s3, github-repo.

boolean

Whether the profile is enabled. Defaults to true.

boolean

Whether to set this as the default profile. Defaults to false.

object

Provider-specific non-sensitive configuration (e.g. bucket name, region, root path, repository owner/name).

object

Provider-specific sensitive configuration (e.g. access key, secret key, GitHub token). Values in this object are stored encrypted and are not returned in GET responses.

Response — 201 Created

Returns the created storage profile object.

Example — create an S3 profile

curl -X POST http://localhost:5121/api/v1/system/storage/providers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-s3",
    "displayName": "My S3 Bucket",
    "providerType": "s3",
    "isEnabled": true,
    "isDefault": false,
    "configuration": {
      "bucketOrContainer": "nekohub-assets",
      "region": "us-east-1",
      "publicBaseUrl": "https://cdn.example.com"
    },
    "secretConfiguration": {
      "accessKey": "AKIAIOSFODNN7EXAMPLE",
      "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'

Update a storage profile

PATCH /api/v1/system/storage/providers/{id}

Updates an existing storage provider profile. Only fields you include are changed. Required permission: providers.update

Path parameters

string (uuid)

required

The unique identifier of the profile to update.

Request body

string

New internal name. Omit to leave unchanged.

string

New display name. Omit to leave unchanged.

boolean

New enabled state. Omit to leave unchanged.

object

Updated non-sensitive configuration. Omit to leave unchanged.

object

Updated sensitive configuration. Omit to leave unchanged.

Response — 200 OK

Returns the updated storage profile object.

Example

curl -X PATCH http://localhost:5121/api/v1/system/storage/providers/01956f8d-0000-0000-0000-000000000010 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Primary S3 Bucket", "isEnabled": true}'

Delete a storage profile

DELETE /api/v1/system/storage/providers/{id}

Deletes a storage provider profile. Existing assets stored under this profile are not automatically migrated or deleted. Required permission: providers.delete

Path parameters

string (uuid)

required

The unique identifier of the profile to delete.

Response

object

Show properties

string (uuid)

ID of the deleted profile.

boolean

Whether this profile was the default at time of deletion.

string

Final status.

string (ISO 8601)

Deletion timestamp.

Example

curl -X DELETE http://localhost:5121/api/v1/system/storage/providers/01956f8d-0000-0000-0000-000000000010 \
  -H "Authorization: Bearer <token>"

Set default storage profile

POST /api/v1/system/storage/providers/{id}/set-default

Marks the specified profile as the default storage profile for new asset uploads. Required permission: settings.update

Path parameters

string (uuid)

required

The unique identifier of the profile to set as default.

Response — 200 OK

Returns the updated storage profile object.

Example

curl -X POST http://localhost:5121/api/v1/system/storage/providers/01956f8d-0000-0000-0000-000000000010/set-default \
  -H "Authorization: Bearer <token>"

Browse a GitHub Repo directory

GET /api/v1/system/storage/providers/{id}/github-repo/browse

Lists files and directories within a GitHub-based storage profile. Only available for profiles with providerType: github-repo. Required permission: providers.read

Path parameters

string (uuid)

required

The unique identifier of a github-repo storage profile.

Query parameters

string

Directory path to browse. Defaults to the repository root.

boolean

Whether to list contents recursively.

integer

Maximum recursion depth when recursive is true.

string

Filter by entry type: file, dir, or omit for all.

string

Filter entries by name keyword.

integer

Page number. Defaults to 1.

integer

Results per page.

Response

object

Show properties

string (uuid)

The storage profile ID.

string

The path that was browsed.

integer

Total matching entries.

integer

Current page.

integer

Items per page.

boolean

Whether more pages are available.

array

Show item properties

string

Entry name.

string

Full path within the repository.

string

Entry type: file or dir.

boolean

Whether this entry is a directory.

boolean

Whether this entry is a file.

integer

File size in bytes (files only).

string

Git blob SHA.

string

Public URL for the file, if applicable.

Example

curl "http://localhost:5121/api/v1/system/storage/providers/01956f8d-0000-0000-0000-000000000010/github-repo/browse?path=images&page=1&pageSize=20" \
  -H "Authorization: Bearer <token>"

Upsert a file in a GitHub Repo

POST /api/v1/system/storage/providers/{id}/github-repo/upsert

Creates or updates a single file in a GitHub-based storage profile. Required permission: providers.update

Path parameters

string (uuid)

required

The unique identifier of a github-repo storage profile.

Request body

string

required

Path within the repository where the file should be written (e.g. images/2026/photo.png).

string

required

Base64-encoded content of the file to write.

string

Optional commit message. Defaults to a generated message if omitted.

string

For updates: the current file’s Git blob SHA. Required when updating an existing file to prevent conflicts. Omit when creating a new file.

Response

object

Show properties

string (uuid)

The storage profile ID.

string

The path where the file was written.

string

Whether the operation was a create or update.

integer

File size in bytes.

string

New Git blob SHA.

string

Public URL for the file, if applicable.

Returns 409 Conflict if the expectedSha does not match the current file SHA.

Example

curl -X POST http://localhost:5121/api/v1/system/storage/providers/01956f8d-0000-0000-0000-000000000010/github-repo/upsert \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "images/hello.txt",
    "contentBase64": "SGVsbG8sIHdvcmxkIQ==",
    "commitMessage": "Add hello.txt"
  }'

Overview

Endpoints

Storage Providers

Get storage providers overview

Response

Example

Create a storage profile

Request body

Response — 201 Created

Example — create an S3 profile

Update a storage profile

Path parameters

Request body

Response — 200 OK

Example

Delete a storage profile

Path parameters

Response

Example

Set default storage profile

Path parameters

Response — 200 OK

Example

Browse a GitHub Repo directory

Path parameters

Query parameters

Response

Example

Upsert a file in a GitHub Repo

Path parameters

Request body

Response

Example

​Get storage providers overview

​Response

​Example

​Create a storage profile

​Request body

​Response — 201 Created

​Example — create an S3 profile

​Update a storage profile

​Path parameters

​Request body

​Response — 200 OK

​Example

​Delete a storage profile

​Path parameters

​Response

​Example

​Set default storage profile

​Path parameters

​Response — 200 OK

​Example

​Browse a GitHub Repo directory

​Path parameters

​Query parameters

​Response

​Example

​Upsert a file in a GitHub Repo

​Path parameters

​Request body

​Response

​Example

Get storage providers overview

Response

Example

Create a storage profile

Request body

Response — 201 Created

Example — create an S3 profile

Update a storage profile

Path parameters

Request body

Response — 200 OK

Example

Delete a storage profile

Path parameters

Response

Example

Set default storage profile

Path parameters

Response — 200 OK

Example

Browse a GitHub Repo directory

Path parameters

Query parameters

Response

Example

Upsert a file in a GitHub Repo

Path parameters

Request body

Response

Example