Namespaces
asset
Methods and types of the `asset` namespace (`client.asset` / `bot.asset`).
Interfaces
AssetWithChats
Extends
Omit<Asset,"chats">
Properties
| Property | Type | Description | Inherited from |
|---|---|---|---|
aiGenerated? | boolean | True when the bytes were produced by a platform AI process (e.g. promoted from an aiRevision scratch row). Drives the "AI Generated" system chip in the asset view; also queryable for admin filtering. Distinct from user tags — set at create/promote time, not editable. | Omit.aiGenerated |
chats? | { creator?: Chat; reviewer?: Chat; } | - | - |
chats.creator? | Chat | - | - |
chats.reviewer? | Chat | - | - |
checksum | string | Client-supplied fingerprint of the original, used to spot duplicate uploads. The web and mobile apps send a SHA-256 of the whole file up to 4 MB and of its first 2 MB, last 2 MB and size beyond that; older SDK callers sent MD5. It is not a full-file hash — see contentSha256. | Omit.checksum |
checksumAlgorithm? | string | null | The algorithm used for computing the checksum, when recorded. | Omit.checksumAlgorithm |
contentSha256? | string | null | Full-file SHA-256 of the original, computed server-side once the upload has been read. Null until then. | Omit.contentSha256 |
createdAt? | number | The timestamp when the asset was created. Format int64 | Omit.createdAt |
creator? | PublicUser | Public user information of the creator. | Omit.creator |
creatorId | string | The ID of the user who created the asset. Format objectId | Omit.creatorId |
everPublic? | boolean | One-way flag set true once the asset has been publicly exposed (link or file system) at any point. | Omit.everPublic |
expectedUploadSizeInMB | number | Expected upload size of the asset in megabytes, used to determine signed link generation. | Omit.expectedUploadSizeInMB |
files? | File[] | The files associated with the asset. | Omit.files |
fileSystemPaths? | string[] | Array of file system entry IDs associated with this asset. Format objectId | Omit.fileSystemPaths |
folder? | string | Folder | null | Populated folder data. | Omit.folder |
folderId? | string | null | If the asset is in a folder the folder ID goes here. If not this is null. Format objectId Default null | Omit.folderId |
functionType | "avatar" | "attachment" | "media" | "logo" | "icon" | The function of the asset on the platform. | Omit.functionType |
hasActivePublicFileSystem? | boolean | True when the asset is a member of at least one active, non-expired public file system. | Omit.hasActivePublicFileSystem |
hasActivePublicLink? | boolean | True when the asset has at least one active public download link. | Omit.hasActivePublicLink |
id | string | The id of the asset. Format objectId | Omit.id |
inheritance? | any | Populated inheritance data. | Omit.inheritance |
inheritanceId? | string | null | ID of the inheritance object associated with this asset. Format objectId | Omit.inheritanceId |
keepOriginal? | boolean | True when the asset is exempt from pruning. | Omit.keepOriginal |
keyPath | string | The path used by the file system (like an S3 bucket) for the asset. | Omit.keyPath |
mediaType | "image" | "video" | "audio" | "3d" | "document" | "file" | The media type of the asset. | Omit.mediaType |
meta? | Record<string, any> | Additional metadata for the asset. Default {} | Omit.meta |
name | string | The name of the asset used on the platform. | Omit.name |
originalExtension? | string | null | Lower-case extension of the original file, without the dot. | Omit.originalExtension |
originalName? | string | null | The file name the original was uploaded under. Unlike name it does not change when the asset is renamed. Best effort for assets uploaded before it was recorded. | Omit.originalName |
originalSizeInBytes? | number | null | Size of the original file in bytes. Unlike sizeInBytes, which totals every file the asset holds, this is the upload alone. | Omit.originalSizeInBytes |
originalState? | "stored" | "pruneRequested" | "pruning" | "pruned" | "restoring" | Where the original file is: stored while it is in storage, otherwise pruned or in transition. restoring: a pruned original is being re-attached — uploaded, or verified against its recorded hash. | Omit.originalState |
ownerResourceId | string | The id of the resource that the asset is attached to. Format objectId | Omit.ownerResourceId |
ownerResourceType | "project" | "chatMessage" | "user" | The type of the owner resource. | Omit.ownerResourceType |
processingCompletedAt? | number | null | When post-processing finished (Unix ms), or null while it is running or has not run. | Omit.processingCompletedAt |
pruneAfter? | number | null | When a requested prune runs (Unix ms): the end of the undo window, or the next retry after a failed attempt. | Omit.pruneAfter |
pruneAttempts? | number | Failed prune attempts since the last success or request. | Omit.pruneAttempts |
prunedAt? | number | null | When the original was pruned (Unix ms). | Omit.prunedAt |
pruneError? | string | null | Why the last prune attempt failed, or why the policy set the asset aside. | Omit.pruneError |
pruneReason? | "manual" | "policy" | null | Whether a person or the project policy asked for the prune. | Omit.pruneReason |
pruneRequestedById? | string | null | Who requested the waiting prune; null for the project policy. | Omit.pruneRequestedById |
publishedOn? | string | null | The date when the asset was published. If not published, this will be null. Format date-time Default null | Omit.publishedOn |
publisher? | PublicUser | Public user information of the publisher (if published). | Omit.publisher |
publisherId? | string | null | The ID of the user who published the asset (if published). Format objectId Default null | Omit.publisherId |
reattachById? | string | null | While restoring, who started the re-attach. | Omit.reattachById |
reattachStartedAt? | number | null | While restoring, when the re-attach upload was started (Unix ms). | Omit.reattachStartedAt |
reattachUploadId? | string | null | While restoring, the upload the file is arriving through; null once it is being verified. | Omit.reattachUploadId |
sizeInBytes | number | The total size of the asset in bytes. | Omit.sizeInBytes |
slug? | string | The URL-friendly slug of the asset name. | Omit.slug |
status | "active" | "pendingDelete" | "inactive" | The status of the asset. Default active | Omit.status |
submissionFileSystemIds? | string[] | Submission file system IDs the asset currently belongs to. Empty when not in any submission. | Omit.submissionFileSystemIds |
tags? | string[] | Tags associated with the asset. Format objectId | Omit.tags |
updatedAt? | number | The timestamp when the asset was last updated. Format int64 | Omit.updatedAt |
visibility? | ("creator" | "reviewer" | "member" | "public")[] | The visibility settings for the asset. Default ['creator'] | Omit.visibility |
Chat
Properties
CompleteMultipartUploadData
Properties
CreateAssetShortLinkData
Properties
CreateAssetShortLinkResponse
Properties
| Property | Type |
|---|---|
shortLink | ShortLink |
shortUrl | string |
DocumentViewUrlResponse
Properties
GetAssetPageParams
Properties
GetAssetParams
Properties
MultipartUploadOptions
Properties
| Property | Type |
|---|---|
abortSignal? | AbortSignal |
assetId? | string |
enableProgressPersistence? | boolean |
fileName? | string |
fileSize? | number |
maxRetries? | number |
onProgress? | (progress) => void |
projectId? | string |
sessionId? | string |
MultipartUploadResult
Properties
PartUploadOptions
Properties
PublicAssetLink
Properties
| Property | Type | Description |
|---|---|---|
assetId | string | - |
createdAt | string | - |
creatorId | string | - |
expires | string | null | - |
id | string | - |
isExpired? | boolean | - |
mode? | PublicAssetLinkMode | Capability mode for this link. - 'download' — direct-download link only; embed iframe blocked. - 'embed' — embeddable iframe only; direct download blocked. - 'embed-download' — both endpoints allowed (default; backward-compatible). Enforced server-side at /v1/public-download/{token}/download and /embed-files. |
projectId | string | - |
publicUrl | string | - |
status | "active" | "expired" | "disabled" | - |
token | string | - |
updatedAt | string | - |
ShortLink
Properties
TagAssetData
Properties
UntagAssetData
Properties
UpdateAssetData
Properties
Type Aliases
AssetPageResponse
type AssetPageResponse = {
page: number;
};Properties
AssetResponse
type AssetResponse = AssetWithChats;DownloadAssetsResponse
type DownloadAssetsResponse = any[];FileResponse
type FileResponse = File;PublicAssetLinkMode
type PublicAssetLinkMode = "download" | "embed" | "embed-download";RepairAssetsResponse
type RepairAssetsResponse = any[];Functions
default()
function default(client): {
cancelPruneOriginal: Promise<Asset>;
cancelReattachOriginal: Promise<Asset>;
cleanupUploadSessions: void;
completeCustomThumbnailUpload: Promise<{
key: string;
status: string;
}>;
completeReattachOriginal: Promise<Asset>;
completeUpload: Promise<any>;
completeUploadSession: void;
createPublicLink: Promise<PublicAssetLink>;
createShortLink: Promise<CreateAssetShortLinkResponse>;
deleteAsset: Promise<AssetWithChats>;
disablePublicLink: Promise<PublicAssetLink>;
downloadAssets: Promise<DownloadAssetsResponse>;
getAsset: Promise<AssetWithChats>;
getAssetAccessActivity: Promise<{
breakdown: {
count: number;
label: string;
value: string;
}[];
eventType: string | null;
from: string;
groupBy: string;
range: string;
series: {
count: number;
date: string;
eventType: string;
}[];
to: string;
totals: {
count: number;
eventType: string;
}[];
}>;
getAssetPage: Promise<AssetPageResponse>;
getAssetReferences: Promise<AssetReferences>;
getCustomThumbnailUploadUrl: Promise<{
assetId: string;
expires: number;
fileName: string;
key: string;
mimeType: string;
status: string;
uploadId: string;
urls: string[];
}>;
getDocumentViewUrl: Promise<DocumentViewUrlResponse>;
getFile: Promise<File>;
getFilesByFunctionType: Promise<File[]>;
getOriginal: Promise<AssetOriginalStatus>;
getOriginalHistory: Promise<{
results: AssetOriginalHistoryEntry[];
}>;
getPublicLinks: Promise<{
results: PublicAssetLink[];
}>;
getUploadSession: UploadSessionData | null;
getUploadSessions: UploadSessionData[];
hasActiveUploads: boolean;
multipartUpload: Promise<MultipartUploadResult>;
offUploadSessionMessage: void;
onUploadSessionMessage: void;
promoteAttachmentToProject: Promise<{
asset: Asset;
deduped: boolean;
}>;
pruneOriginal: Promise<Asset>;
reactivatePublicLink: Promise<PublicAssetLink>;
reattachOriginal: Promise<Asset>;
recordAccessActivity: Promise<void>;
removeCustomThumbnail: Promise<Asset>;
removeUploadSession: void;
repairAssets: Promise<RepairAssetsResponse>;
setKeepOriginal: Promise<Asset>;
startReattachOriginal: Promise<AssetOriginalReattachStart>;
tagAsset: Promise<AssetWithChats>;
untagAsset: Promise<AssetWithChats>;
updateAsset: Promise<AssetWithChats>;
updatePublicLink: Promise<PublicAssetLink>;
};Defines asset-related methods for the NuramaClient.
Parameters
| Parameter | Type | Description |
|---|---|---|
client | default | The NuramaClient instance. |
Returns
An object containing the asset-related methods.
| Name | Type | Description |
|---|---|---|
cancelPruneOriginal() | (assetId) => Promise<Asset> | Cancels a requested prune before it runs. Needs canPruneAsset. |
cancelReattachOriginal() | (assetId) => Promise<Asset> | Cancels a re-attach whose upload has not completed; the original is pruned again. |
cleanupUploadSessions() | (projectId, olderThanMs?) => void | Clean up old upload sessions for a project |
completeCustomThumbnailUpload() | (assetId, data) => Promise<{ key: string; status: string; }> | Finalize the multipart S3 upload for a custom thumbnail. Triggers the post-processing Lambda by committing the S3 object. |
completeReattachOriginal() | (assetId, data) => Promise<Asset> | Completes a re-attach upload. The file is verified against the original's SHA-256 in the background: the asset comes back still restoring, and the outcome arrives as an assetOriginalStateUpdate (stored when it matched, pruned when it did not). |
completeUpload() | (uploadData) => Promise<any> | Complete a multipart upload initiated by createAssets. Matches the route (POST /v1/assets/complete-upload) and mirrors nuramaClient.scratch.completeUpload, so moving between the asset and scratch namespaces uses the same verb. |
completeUploadSession() | (projectId, sessionId) => void | Mark an upload session as completed |
createPublicLink() | (assetId, data) => Promise<PublicAssetLink> | Create a public download link for an asset. |
createShortLink() | (assetId, data?) => Promise<CreateAssetShortLinkResponse> | Creates a short link for an asset. If a short link already exists for the asset with the same visibility, returns the existing one. |
deleteAsset() | (assetId) => Promise<AssetWithChats> | Deletes an asset (marks for deletion). |
disablePublicLink() | (assetId, linkId) => Promise<PublicAssetLink> | Disable a public download link. |
downloadAssets() | (assetIds) => Promise<DownloadAssetsResponse> | Generates signed download URLs for the original files of specified assets. |
getAsset() | (assetId, params?) => Promise<AssetWithChats> | Retrieves a specific asset by its ID with optional chat data. |
getAssetAccessActivity() | (assetId, params?) => Promise<{ breakdown: { count: number; label: string; value: string; }[]; eventType: string | null; from: string; groupBy: string; range: string; series: { count: number; date: string; eventType: string; }[]; to: string; totals: { count: number; eventType: string; }[]; }> | Get aggregated access-activity for a single asset. Returns totals per eventType, a breakdown for the requested dimension, and a zero-filled daily series. |
getAssetPage() | (assetId, params?) => Promise<AssetPageResponse> | Gets the page number an asset appears on based on specified filters and sorting. |
getAssetReferences() | (assetId) => Promise<AssetReferences> | Lists every location an asset is referenced — its primary file system and each secondary reference (reviewer, submission, public), grouped and counted. Renaming an asset retitles it at every one of these locations, and deleting its last primary reference removes them all — so this is what the rename and delete confirmations show the user before either happens. |
getCustomThumbnailUploadUrl() | (assetId, data) => Promise<{ assetId: string; expires: number; fileName: string; key: string; mimeType: string; status: string; uploadId: string; urls: string[]; }> | Mint a signed multipart upload URL for a user-supplied custom thumbnail image. The upload lands in the originals bucket tagged so the post-processing Lambda generates the customThumbnail outputs and registers them on the asset via the file-update callback. Caller flow: 1. multipartUpload(file, response.urls, response.key, response.uploadId) 2. completeCustomThumbnailUpload({ assetId, key, uploadId, parts }) 3. wait for the assetFileUpdate websocket event |
getDocumentViewUrl() | (assetId) => Promise<DocumentViewUrlResponse> | Mints a short-lived signed URL for rendering a document inline. Documents keep their media PDF in the private bucket, so unlike images and video it cannot be addressed by keyPath through the file CDN. Fetch this per document open; do not cache it past expires. |
getFile() | (assetId, fileId) => Promise<File> | Retrieves a specific file from an asset. |
getFilesByFunctionType() | (assetId, functionType) => Promise<File[]> | Retrieves files of a specific function type from an asset. |
getOriginal() | (assetId) => Promise<AssetOriginalStatus> | Where an asset's original is, what the project's pruning policy will do with it, and whether it can be pruned by hand now. Needs canGetAssetOriginal. |
getOriginalHistory() | (assetId) => Promise<{ results: AssetOriginalHistoryEntry[]; }> | The history of an asset's original, newest first. Needs canGetAssetOriginal. |
getPublicLinks() | (assetId, options?) => Promise<{ results: PublicAssetLink[]; }> | Get all public download links for an asset. |
getUploadSession() | (projectId, sessionId) => UploadSessionData | null | Get a specific upload session |
getUploadSessions() | (projectId) => UploadSessionData[] | Get all active upload sessions for a project |
hasActiveUploads() | (staleMs?) => boolean | True when any upload is genuinely in flight anywhere in the app (across all projects and tabs). Intended for app-level guards — e.g. suppressing an automatic version-update page refresh while bytes are still uploading. Stale (crashed-tab) sessions are ignored via the freshness window. |
multipartUpload() | ( file, signedUrls, key, uploadId, options? ) => Promise<MultipartUploadResult> | Uploads a file using multipart upload with the provided signed URLs |
offUploadSessionMessage() | (listenerId) => void | Unregister a cross-tab upload session message listener |
onUploadSessionMessage() | (listenerId, callback) => void | Register a listener for cross-tab upload session messages |
promoteAttachmentToProject() | (assetId, payload) => Promise<{ asset: Asset; deduped: boolean; }> | Promote a chat-message attachment into a project as a fresh, independent project asset. The source attachment is left untouched; the new project asset has its own lifecycle, post-processing pipeline, and storage footprint. Idempotent: a second promote of the same source into the same project returns the existing promoted asset with deduped: true. Requires canCreateAsset on the destination project — reviewers are blocked. The server additionally rejects when the source attachment's workspace doesn't match the destination project's. |
pruneOriginal() | (assetId) => Promise<Asset> | Requests that an asset's original be pruned once the undo window has passed (pruneAfter). Needs canPruneAsset. |
reactivatePublicLink() | ( assetId, linkId, data? ) => Promise<PublicAssetLink> | Reactivate a disabled/expired public download link. |
reattachOriginal() | ( assetId, file, options ) => Promise<Asset> | Re-attaches a pruned original from a file: starts the re-attach, uploads the file and completes it. Aborting (abortSignal) or a failed upload cancels the re-attach. Resolves once the upload is committed; the verification outcome arrives as an assetOriginalStateUpdate. |
recordAccessActivity() | (assetId, body) => Promise<void> | Record an authenticated play event from the in-app player. Fire-and-forget; server returns 204. Throw-on-failure is fine because the caller already de-dupes per session. |
removeCustomThumbnail() | (assetId) => Promise<Asset> | Remove the custom thumbnail from an asset. Soft-deletes all custom thumb files; the asset falls back to the auto-generated thumbnail. |
removeUploadSession() | (projectId, sessionId) => void | Remove an upload session |
repairAssets() | (assetIds) => Promise<RepairAssetsResponse> | Attempts to repair assets (e.g., regenerate signed URLs for pending uploads). |
setKeepOriginal() | (assetId, keepOriginal) => Promise<Asset> | Exempts an asset from pruning, or lifts the exemption. Needs canPruneAsset. |
startReattachOriginal() | (assetId, data) => Promise<AssetOriginalReattachStart> | Starts re-attaching a pruned original. The size and the upload fingerprint (checksum) are checked against the original's first, so a wrong file is refused before it is sent (assetOriginalMismatch, 422). Needs canReattachAssetOriginal, or canReattachOwnAssetOriginal on an asset you created. Upload the parts with multipartUpload, then call completeReattachOriginal — or use reattachOriginal, which does all three. |
tagAsset() | (assetId, tagData) => Promise<AssetWithChats> | Tags an asset with a specific tag. |
untagAsset() | (assetId, untagData) => Promise<AssetWithChats> | Untags an asset by removing a specific tag. |
updateAsset() | (assetId, updateData) => Promise<AssetWithChats> | Updates an asset. |
updatePublicLink() | ( assetId, linkId, data ) => Promise<PublicAssetLink> | Update a public download link (extend expiration or change status). |