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.).

description

string

Optional description for the asset. Maximum 1000 characters.

altText

string

Optional alt text for the asset. Maximum 1000 characters.

isPublic

boolean

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

storageProviderProfileId

string (uuid)

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

runEnrichment

boolean

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

commitMessage

string

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

Response — 202 Accepted

data

object

Show properties

string (uuid)

Unique asset identifier.

type

string

Asset type. Currently always image.

status

string

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

originalFileName

string

The original filename provided at upload.

contentType

string

MIME type of the uploaded file.

size

integer

File size in bytes.

width

integer

Image width in pixels, populated after processing.

height

integer

Image height in pixels, populated after processing.

storageProvider

string

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

storageProviderProfileId

string (uuid)

The storage profile ID used.

storageKey

string

Internal storage key for the asset.

publicUrl

string

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

isPublic

boolean

Whether the asset is publicly accessible.

description

string

Asset description.

altText

string

Asset alt text.

createdAtUtc

string (ISO 8601)

Creation timestamp.

updatedAtUtc

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

page

integer

Page number. Defaults to 1.

pageSize

integer

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

query

string

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

contentType

string

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

status

string

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

orderBy

string

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

orderDirection

string

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

Response

data

object

Show properties

items

array

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

page

integer

Current page number.

pageSize

integer

Items per page.

total

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

data

object

Show properties

string (uuid)

Unique identifier.

type

string

Asset type.

status

string

Processing status.

originalFileName

string

Original filename.

storedFileName

string

The name under which the file is stored.

contentType

string

MIME type.

extension

string

File extension.

size

integer

File size in bytes.

width

integer

Image width in pixels.

height

integer

Image height in pixels.

checksumSha256

string

SHA-256 checksum of the file content.

storageProvider

string

Storage provider type.

storageProviderProfileId

string (uuid)

Storage profile ID.

storageKey

string

Internal storage key.

publicUrl

string

Public content URL (if public).

isPublic

boolean

Whether the asset is publicly accessible.

description

string

Asset description.

altText

string

Asset alt text.

createdAtUtc

string (ISO 8601)

Creation timestamp.

updatedAtUtc

string (ISO 8601)

Last updated timestamp.

derivatives

array

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

structuredResults

array

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

latestExecutionSummary

object

Summary of the most recent skill execution on this asset.

Show properties

executionId

string (uuid)

Execution identifier.

skillName

string

Name of the skill that ran.

triggerSource

string

How the execution was triggered.

startedAtUtc

string (ISO 8601)

When the execution started.

completedAtUtc

string (ISO 8601)

When the execution completed.

succeeded

boolean

Whether the execution succeeded overall.

steps

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

description

string

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

altText

string

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

originalFileName

string

New original filename. Omit to leave unchanged.

isPublic

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)

commitMessage

string

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

Response

data

object

Show properties

string (uuid)

ID of the deleted asset.

status

string

Final status of the asset before deletion.

deletedAtUtc

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

ids

array of strings (uuid)

required

An array of asset IDs to delete.

Response

data

object

Show properties

requestedCount

integer

Number of IDs provided in the request.

deletedCount

integer

Number of assets successfully deleted.

notFoundIds

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

data

array

Show item properties

skillName

string

Unique identifier name of the skill.

description

string

Human-readable description of what the skill does.

steps

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.

skillName

string

required

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

Request body (optional)

parameters

object

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

Response

data

object

Show properties

succeeded

boolean

Whether the skill execution succeeded overall.

skillName

string

The name of the skill that ran.

steps

array

Individual step results.

Show step properties

name

string

Step name.

succeeded

boolean

Whether this step succeeded.

errorMessage

string

Error message if this step failed.

asset

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

data

object

Show properties

totalAssets

integer

Total number of assets in the system.

totalBytes

integer

Total storage used across all assets, in bytes.

totalDerivatives

integer

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

contentTypeBreakdown

array

Per-content-type usage breakdown.

Show item properties

contentType

string

MIME type.

count

integer

Number of assets with this content type.

totalBytes

integer

Total bytes for assets with this content type.

mostActiveSkill

object

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

Show properties

skillName

string

Name of the skill.

runCount

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