Nurama Developers
Namespaces

asset

Methods and types of the `asset` namespace (`client.asset` / `bot.asset`).

Interfaces

AssetWithChats

Extends

  • Omit<Asset, "chats">

Properties

PropertyTypeDescriptionInherited from
aiGenerated?booleanTrue 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--
checksumstringClient-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 | nullThe algorithm used for computing the checksum, when recorded.Omit.checksumAlgorithm
contentSha256?string | nullFull-file SHA-256 of the original, computed server-side once the upload has been read. Null until then.Omit.contentSha256
createdAt?numberThe timestamp when the asset was created. Format int64Omit.createdAt
creator?PublicUserPublic user information of the creator.Omit.creator
creatorIdstringThe ID of the user who created the asset. Format objectIdOmit.creatorId
everPublic?booleanOne-way flag set true once the asset has been publicly exposed (link or file system) at any point.Omit.everPublic
expectedUploadSizeInMBnumberExpected 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 objectIdOmit.fileSystemPaths
folder?string | Folder | nullPopulated folder data.Omit.folder
folderId?string | nullIf the asset is in a folder the folder ID goes here. If not this is null. Format objectId Default nullOmit.folderId
functionType"avatar" | "attachment" | "media" | "logo" | "icon"The function of the asset on the platform.Omit.functionType
hasActivePublicFileSystem?booleanTrue when the asset is a member of at least one active, non-expired public file system.Omit.hasActivePublicFileSystem
hasActivePublicLink?booleanTrue when the asset has at least one active public download link.Omit.hasActivePublicLink
idstringThe id of the asset. Format objectIdOmit.id
inheritance?anyPopulated inheritance data.Omit.inheritance
inheritanceId?string | nullID of the inheritance object associated with this asset. Format objectIdOmit.inheritanceId
keepOriginal?booleanTrue when the asset is exempt from pruning.Omit.keepOriginal
keyPathstringThe 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
namestringThe name of the asset used on the platform.Omit.name
originalExtension?string | nullLower-case extension of the original file, without the dot.Omit.originalExtension
originalName?string | nullThe 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 | nullSize 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
ownerResourceIdstringThe id of the resource that the asset is attached to. Format objectIdOmit.ownerResourceId
ownerResourceType"project" | "chatMessage" | "user"The type of the owner resource.Omit.ownerResourceType
processingCompletedAt?number | nullWhen post-processing finished (Unix ms), or null while it is running or has not run.Omit.processingCompletedAt
pruneAfter?number | nullWhen a requested prune runs (Unix ms): the end of the undo window, or the next retry after a failed attempt.Omit.pruneAfter
pruneAttempts?numberFailed prune attempts since the last success or request.Omit.pruneAttempts
prunedAt?number | nullWhen the original was pruned (Unix ms).Omit.prunedAt
pruneError?string | nullWhy the last prune attempt failed, or why the policy set the asset aside.Omit.pruneError
pruneReason?"manual" | "policy" | nullWhether a person or the project policy asked for the prune.Omit.pruneReason
pruneRequestedById?string | nullWho requested the waiting prune; null for the project policy.Omit.pruneRequestedById
publishedOn?string | nullThe date when the asset was published. If not published, this will be null. Format date-time Default nullOmit.publishedOn
publisher?PublicUserPublic user information of the publisher (if published).Omit.publisher
publisherId?string | nullThe ID of the user who published the asset (if published). Format objectId Default nullOmit.publisherId
reattachById?string | nullWhile restoring, who started the re-attach.Omit.reattachById
reattachStartedAt?number | nullWhile restoring, when the re-attach upload was started (Unix ms).Omit.reattachStartedAt
reattachUploadId?string | nullWhile restoring, the upload the file is arriving through; null once it is being verified.Omit.reattachUploadId
sizeInBytesnumberThe total size of the asset in bytes.Omit.sizeInBytes
slug?stringThe URL-friendly slug of the asset name.Omit.slug
status"active" | "pendingDelete" | "inactive"The status of the asset. Default activeOmit.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 objectIdOmit.tags
updatedAt?numberThe timestamp when the asset was last updated. Format int64Omit.updatedAt
visibility?("creator" | "reviewer" | "member" | "public")[]The visibility settings for the asset. Default ['creator']Omit.visibility

Chat

Properties

PropertyType
_id?string
id?string
recentMessages?any[]
totalMessages?number

CompleteMultipartUploadData

Properties

PropertyType
assetIdstring
keystring
parts{ ETag: string; PartNumber: number; }[]
uploadIdstring

CreateAssetShortLinkData

Properties

PropertyType
visibility?"creator" | "reviewer"

CreateAssetShortLinkResponse

Properties

PropertyType
shortLinkShortLink
shortUrlstring

DocumentViewUrlResponse

Properties

PropertyTypeDescription
expiresnumberUnix seconds. Refetch rather than reusing a URL past this.
originalPageCountnumberPages in the source document. Equals pageCount unless truncated.
pageCountnumberFrom meta.document.pageCount; 0 when processing has not reported it.
pagesTruncatedbooleanTrue when the media PDF holds only the first pageCount pages of a longer document, because post-processing hit its maxPages cap. The PDF itself is internally consistent, so this flag is the only way to know.
truncatedFrom"start" | "end"Which end of the document the media PDF kept. 'start' for everything read front-to-back; 'end' for logs, whose newest lines are at the bottom. Only meaningful when pagesTruncated is true.
urlstringSigned URL for the document's media PDF, served inline.

GetAssetPageParams

Properties

PropertyType
inFolder?boolean
limit?number
sort?Record<string, -1 | 1>
visibility?string

GetAssetParams

Properties

PropertyType
chatMessageLimit?number
chatMessageSort?{ id?: 1 | -1; }
chatMessageSort.id?1 | -1
chatReplyLimit?number
chatReplySort?{ id?: 1 | -1; }
chatReplySort.id?1 | -1
chatVisibility?"creator" | "reviewer"

MultipartUploadOptions

Properties

PropertyType
abortSignal?AbortSignal
assetId?string
enableProgressPersistence?boolean
fileName?string
fileSize?number
maxRetries?number
onProgress?(progress) => void
projectId?string
sessionId?string

MultipartUploadResult

Properties

PropertyType
keystring
parts{ ETag: string; PartNumber: number; }[]
uploadIdstring

PartUploadOptions

Properties

PropertyType
abortSignal?AbortSignal
maxRetries?number
onPartProgress?(progress) => void

Properties

PropertyTypeDescription
assetIdstring-
createdAtstring-
creatorIdstring-
expiresstring | null-
idstring-
isExpired?boolean-
mode?PublicAssetLinkModeCapability 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.
projectIdstring-
publicUrlstring-
status"active" | "expired" | "disabled"-
tokenstring-
updatedAtstring-

Properties

PropertyType
codestring
createdAtstring
creatorIdstring
idstring
resourceIdstring
resourceType"asset" | "project" | "workspace" | "chatMessage" | "chatSubmission"
updatedAt?string
visibility"creator" | "reviewer" | null

TagAssetData

Properties

PropertyType
tagIdstring

UntagAssetData

Properties

PropertyType
tagIdstring

UpdateAssetData

Properties

PropertyType
folderId?string | null
meta?Record<string, any>
name?string
tags?string[]

Type Aliases

AssetPageResponse

type AssetPageResponse = {
  page: number;
};

Properties

PropertyType
pagenumber

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

ParameterTypeDescription
clientdefaultThe NuramaClient instance.

Returns

An object containing the asset-related methods.

NameTypeDescription
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?) => voidClean 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) => voidMark 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 | nullGet a specific upload session
getUploadSessions()(projectId) => UploadSessionData[]Get all active upload sessions for a project
hasActiveUploads()(staleMs?) => booleanTrue 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) => voidUnregister a cross-tab upload session message listener
onUploadSessionMessage()(listenerId, callback) => voidRegister 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) => voidRemove 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).

On this page