Assets - NekoHub

All asset management endpoints require authentication via JWT Bearer token or API key. See Authentication for details.

Upload an asset

POST /api/v1/assets
Content-Type: multipart/form-data

Uploads a new image asset. The request must be multipart/form-data. On success, the server returns 202 Accepted and begins background processing (enrichment, derivative generation) if runEnrichment is enabled.

Request fields

file

required

The image file to upload. Must not be empty. Allowed content types are configured server-side (typically image/png, image/jpeg, image/gif, image/webp, etc.).

string

Optional description for the asset. Maximum 1000 characters.

string

Optional alt text for the asset. Maximum 1000 characters.

boolean

Whether the asset should be publicly accessible. Defaults to true.

string (uuid)

Optional. The ID of the storage provider profile to use. If omitted, the default storage provider is used.

boolean

Whether to run AI enrichment after upload. Defaults to true.

string

Optional commit message for storage providers that support it (e.g. GitHub Repo).

Response — 202 Accepted

object

Show properties

string (uuid)

Unique asset identifier.

string

Asset type. Currently always image.

string

Processing status. One of: pending, processing, ready, failed.

string

The original filename provided at upload.

string

MIME type of the uploaded file.

integer

File size in bytes.

integer

Image width in pixels, populated after processing.

integer

Image height in pixels, populated after processing.

string

The storage provider type used (e.g. local, s3, github-repo).

string (uuid)

The storage profile ID used.

string

Internal storage key for the asset.

string

Public URL for the asset (if isPublic is true).

boolean

Whether the asset is publicly accessible.

string

Asset description.

string

Asset alt text.

string (ISO 8601)

Creation timestamp.

string (ISO 8601)

Last updated timestamp.

Errors

Code	Description
`asset_file_required`	The `file` field was not included in the request.
`asset_file_empty`	The uploaded file has zero bytes.
`asset_file_too_large`	The file exceeds the configured maximum upload size.
`asset_content_type_not_allowed`	The file’s content type is not in the allowed list.
`asset_description_too_long`	Description exceeds 1000 characters.
`asset_alt_text_too_long`	Alt text exceeds 1000 characters.

Example

curl -X POST http://localhost:5121/api/v1/assets \
  -H "Authorization: Bearer <token>" \
  -F "file=@kitten.png" \
  -F "description=A fluffy orange kitten" \
  -F "altText=Orange cat looking at camera" \
  -F "isPublic=true" \
  -F "runEnrichment=true"

List assets

GET /api/v1/assets

Returns a paginated list of all assets visible to the authenticated user.

Query parameters

integer

Page number. Defaults to 1.

integer

Number of results per page. Defaults to the server-configured default, capped at the configured maximum.

string

Free-text search. Also accepted as keyword. Matches file name, description, and alt text.

string

Filter by MIME type (e.g. image/jpeg).

string

Filter by processing status. One of: pending, processing, ready, failed.

string

Field to sort by. Also accepted as sortBy. Supported values: createdAtUtc (default), size.

string

Sort direction. Also accepted as sortDirection. One of: asc, desc (default).

Response

object

Show properties

array

Array of asset list items. Each item has: id, type, status, originalFileName, contentType, size, width, height, storageProvider, storageProviderProfileId, publicUrl, isPublic, createdAtUtc, updatedAtUtc.

integer

Current page number.

integer

Items per page.

integer

Total matching asset count.

Example

curl "http://localhost:5121/api/v1/assets?page=1&pageSize=20&orderBy=createdAtUtc&orderDirection=desc" \
  -H "Authorization: Bearer your-api-key"

Get an asset

GET /api/v1/assets/{id}

Returns full details for a single asset, including all derivatives and structured AI results.

Path parameters

string (uuid)

required

The unique identifier of the asset.

Response

object

Show properties

string (uuid)

Unique identifier.

string

Asset type.

string

Processing status.

string

Original filename.

string

The name under which the file is stored.

string

MIME type.

string

File extension.

integer

File size in bytes.

integer

Image width in pixels.

integer

Image height in pixels.

string

SHA-256 checksum of the file content.

string

Storage provider type.

string (uuid)

Storage profile ID.

string

Internal storage key.

string

Public content URL (if public).

boolean

Whether the asset is publicly accessible.

string

Asset description.

string

Asset alt text.

string (ISO 8601)

Creation timestamp.

string (ISO 8601)

Last updated timestamp.

array

Derived versions (e.g. thumbnails). Each entry includes: kind, contentType, extension, size, width, height, publicUrl, createdAtUtc.

array

Structured AI results attached to the asset. Each entry includes: kind, payloadJson, createdAtUtc.

object

Summary of the most recent skill execution on this asset.

Show properties

string (uuid)

Execution identifier.

string

Name of the skill that ran.

string

How the execution was triggered.

string (ISO 8601)

When the execution started.

string (ISO 8601)

When the execution completed.

boolean

Whether the execution succeeded overall.

array

Individual step results. Each has: stepName, succeeded, errorMessage, startedAtUtc, completedAtUtc.

Returns 404 Not Found with error code asset_not_found if the asset does not exist.

Example

curl http://localhost:5121/api/v1/assets/01956f8d-88e4-7c6a-a8f1-5f235293db7a \
  -H "Authorization: Bearer <token>"

Update asset metadata

PATCH /api/v1/assets/{id}

Updates metadata fields for an existing asset. Only fields you include in the request body are changed (patch semantics).

Path parameters

string (uuid)

required

The unique identifier of the asset to update.

Request body

string

New description. Maximum 1000 characters. Omit to leave unchanged.

string

New alt text. Maximum 1000 characters. Omit to leave unchanged.

string

New original filename. Omit to leave unchanged.

boolean

Change public visibility. Omit to leave unchanged.

Response

Returns the full updated asset object (same shape as Get an asset).

Example

curl -X PATCH http://localhost:5121/api/v1/assets/01956f8d-88e4-7c6a-a8f1-5f235293db7a \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "isPublic": false}'

Delete an asset

DELETE /api/v1/assets/{id}

Permanently deletes an asset. This is a hard delete — the asset record and its file in storage are both removed.

Path parameters

string (uuid)

required

The unique identifier of the asset to delete.

Request body (optional)

string

Optional commit message for storage backends that support versioning (e.g. GitHub Repo).

Response

object

Show properties

string (uuid)

ID of the deleted asset.

string

Final status of the asset before deletion.

string (ISO 8601)

Timestamp of deletion.

Returns 404 Not Found with error code asset_not_found if the asset does not exist.

Example

curl -X DELETE http://localhost:5121/api/v1/assets/01956f8d-88e4-7c6a-a8f1-5f235293db7a \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"commitMessage": "Remove test asset"}'

Batch delete assets

POST /api/v1/assets/batch-delete

Deletes multiple assets in one request. Assets that do not exist are silently skipped and reported in notFoundIds.

Request body

array of strings (uuid)

required

An array of asset IDs to delete.

Response

object

Show properties

integer

Number of IDs provided in the request.

integer

Number of assets successfully deleted.

array of strings (uuid)

IDs that were not found and therefore not deleted.

Example

curl -X POST http://localhost:5121/api/v1/assets/batch-delete \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '["01956f8d-88e4-7c6a-a8f1-5f235293db7a", "01956f8d-0000-0000-0000-000000000001"]'

Get asset content

GET /api/v1/assets/{id}/content

Accesses the content of an asset, with access control applied:

Public asset: Returns a 307 Temporary Redirect to the public content URL.
Private asset: Streams the content directly (requires valid JWT or API key).

Path parameters

string (uuid)

required

The unique identifier of the asset.

Returns 404 Not Found with error code asset_not_found if the asset does not exist.

Example

# For a public asset — follow the redirect
curl -L http://localhost:5121/api/v1/assets/01956f8d-88e4-7c6a-a8f1-5f235293db7a/content \
  -H "Authorization: Bearer <token>"

# For a private asset — save to file
curl http://localhost:5121/api/v1/assets/01956f8d-88e4-7c6a-a8f1-5f235293db7a/content \
  -H "Authorization: Bearer <token>" \
  -o asset.png

List available skills

GET /api/v1/assets/skills

Returns a list of AI skills available to run against assets.

Response

array

Show item properties

string

Unique identifier name of the skill.

string

Human-readable description of what the skill does.

array of strings

The processing steps this skill performs.

Example

curl http://localhost:5121/api/v1/assets/skills \
  -H "Authorization: Bearer your-api-key"

Run a skill on an asset

POST /api/v1/assets/{id}/skills/{skillName}/run

Triggers an AI skill to run against a specific asset. Skills can generate captions, alt text, thumbnails, and other derived outputs.

Path parameters

string (uuid)

required

The unique identifier of the asset.

string

required

The name of the skill to run. Use List available skills to discover valid skill names.

Request body (optional)

object

Optional skill-specific parameters as a JSON object. The accepted parameters depend on the skill being run.

Response

object

Show properties

boolean

Whether the skill execution succeeded overall.

string

The name of the skill that ran.

array

Individual step results.

Show step properties

string

Step name.

boolean

Whether this step succeeded.

string

Error message if this step failed.

object

The updated asset object after skill execution.

Example

curl -X POST http://localhost:5121/api/v1/assets/01956f8d-88e4-7c6a-a8f1-5f235293db7a/skills/caption/run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Get usage statistics

GET /api/v1/assets/usage-stats

Returns aggregate usage statistics across all assets.

Response

object

Show properties

integer

Total number of assets in the system.

integer

Total storage used across all assets, in bytes.

integer

Total number of asset derivatives (e.g. thumbnails).

array

Per-content-type usage breakdown.

Show item properties

string

MIME type.

integer

Number of assets with this content type.

integer

Total bytes for assets with this content type.

object

The skill with the most executions, or null if no skills have been run.

Show properties

string

Name of the skill.

integer

Number of times this skill has been executed.

Example

curl http://localhost:5121/api/v1/assets/usage-stats \
  -H "Authorization: Bearer <token>"

{
  "data": {
    "totalAssets": 42,
    "totalBytes": 104857600,
    "totalDerivatives": 38,
    "contentTypeBreakdown": [
      { "contentType": "image/png", "count": 25, "totalBytes": 62914560 },
      { "contentType": "image/jpeg", "count": 17, "totalBytes": 41943040 }
    ],
    "mostActiveSkill": {
      "skillName": "caption",
      "runCount": 30
    }
  }
}

​Upload an asset

​Request fields

​Response — 202 Accepted

​Errors

​Example

​List assets

​Query parameters

​Response

​Example

​Get an asset

​Path parameters

​Response

​Example

​Update asset metadata

​Path parameters

​Request body

​Response

​Example

​Delete an asset

​Path parameters

​Request body (optional)

​Response

​Example

​Batch delete assets

​Request body

​Response

​Example

​Get asset content

​Path parameters

​Example

​List available skills

​Response

​Example

​Run a skill on an asset

​Path parameters

​Request body (optional)

​Response

​Example

​Get usage statistics

​Response

​Example

Upload an asset

Request fields

Response — 202 Accepted

Errors

Example

List assets

Query parameters

Response

Example

Get an asset

Path parameters

Response

Example

Update asset metadata

Path parameters

Request body

Response

Example

Delete an asset

Path parameters

Request body (optional)

Response

Example

Batch delete assets

Request body

Response

Example

Get asset content

Path parameters

Example

List available skills

Response

Example

Run a skill on an asset

Path parameters

Request body (optional)

Response

Example

Get usage statistics

Response

Example