Skip to main content

Uploads

SVRunner handles file uploads through GraphQL multipart requests. There is no separate REST upload API for normal asset upload workflows.

How Uploads Work​

The server exposes an Upload scalar and enables GraphQL multipart handling.

Uploads are primarily used through asset mutations such as:

  • createAsset
  • updateAsset

These mutations accept a file field in their input.

Common Upload Workflows​

Create A New Asset With A File​

The most common upload flow is creating a new asset and including the media file in the same mutation.

Typical input fields include:

  • projectId
  • name
  • extensionId if the asset uses an extension
  • duration
  • file

When a file is provided, the server uploads it and then processes the file metadata.

Replace The File On An Existing Asset​

The update flow can also accept a new file.

This is useful when:

  • correcting an asset without replacing the record
  • updating a source file while preserving scheduling references
  • reprocessing a media item after changes

Server Behavior​

When a file is present in createAsset or updateAsset:

  1. the upload is stored by the asset model
  2. the server processes the file metadata
  3. the asset record is updated with the resulting file information

This is why upload success is about more than transport. A file can upload successfully and still fail during asset processing.

Client Behavior​

The current web client uses apollo-upload-client and uploads files through the same GraphQL endpoint.

The built-in uploader also tracks:

  • upload status
  • upload progress
  • success and error notifications

Uploads are processed one file at a time in the current client workflow.

Example: Create Asset With File​

GraphQL mutation:

mutation CreateAsset($input: CreateAssetInput!) {
  createAsset(input: $input) {
    id
    name
    duration
    fileName
  }
}

Example variables shape:

{
  "input": {
    "projectId": 1,
    "name": "Lobby Reel 01",
    "duration": 15,
    "extensionId": -1,
    "file": null
  }
}

In multipart GraphQL transport, the file value is supplied through the multipart form mapping rather than inline JSON.

Example: Update Asset File​

mutation UpdateAsset($id: Int!, $input: UpdateAssetInput!) {
  updateAsset(id: $id, input: $input) {
    id
    name
    fileName
  }
}

Example variables shape:

{
  "id": 42,
  "input": {
    "file": null
  }
}

Operational Considerations​

Large Files​

Large uploads may take time, especially over slower networks.

For operators, this means the asset may not appear immediately ready for preview or playback.

Metadata Validation​

After upload, verify:

  • duration
  • resolution
  • file type
  • any extension-specific validation

Preferences Affecting Upload Experience​

Project preferences can change asset defaults and preview behavior, including:

  • default duration for image assets
  • whether file-based assets are allowed
  • whether video preview generation is skipped

See Preferences.

Common Failure Cases​

  • sending a normal JSON request instead of multipart GraphQL
  • omitting required asset input fields like projectId
  • uploading a file that fails later during processing
  • assuming upload completion means preview generation is also complete

API Multipart Upload Stub screenshot: GraphQL client or network inspector showing a multipart upload request. Save final image at packages/docs/screenshots/api-multipart-upload.png.