Files

Use Files to manage uploaded, recorded, and processed media. Register a file, create a derivative, copy it to configured storage, or remove it.

What it doesManage a media file

Choose this whenMedia already exists as a file and must be uploaded, processed, copied, or deleted.

Use another module whenUse Recordings when the source is live; Storages only registers the external destination.

1Add or find the file2Process if needed3Reuse or export

POST /api/files/create

Filter endpoints11 endpoints

Before you start

All methods require a valid x-access-token. The instance needs enough local space for upload and processing, and a configured Storage resource before copying to object storage.

What you can do

upload and create add a media asset.
getAll, getCount, and getById inspect the file inventory.
update changes supported file metadata.
copyTo starts a storage copy and getCopyProgress reports progress.
getStat reads available processing status.
remove or removeByPath deletes an asset.

Example workflow

Upload a short test clip and keep the returned file identifier.
Create the required derivative or update its metadata.
Start copyTo for a configured archive destination.
Poll getCopyProgress until the transfer completes.
Verify the archive before removing the local file.

Common use cases

Move completed event recordings to object storage.
Create a playback-ready derivative from an uploaded master.
Clean up local media after retention and archive checks succeed.

Limits and troubleshooting

Large uploads and copies are asynchronous and can fail because of disk space, credentials, network capacity, or an invalid path. Do not remove the source until the destination is verified. Treat user-supplied paths and filenames as untrusted input.

Next steps

Configure Storages for durable retention or Web players when the asset must be published for browser playback.

REST solution recipe

Process a media file and copy it to storage

Create or upload the managed file, monitor any derivative processing, then copy the finished asset to a configured storage target.

Create the managed derivativeChoose the source, output format, and required processing.POST /api/files/create
Monitor processingWait for the background worker to finish.POST /api/files/getStat
Copy to storageSend the finished file to a registered destination.POST /api/files/copyTo
Verify copy completionKeep the source until the progress response confirms completion.POST /api/files/getCopyProgressById

Do not remove the source until processing and copy progress are complete and the destination object has been verified.

POST

/api/files/create

API token required

Create saves a managed file record in the file manager. Use it when an uploaded asset should become something the rest of the platform can work with reliably: a named file, a converted deliverable, or a reusable playback or overlay asset.

This method is more than metadata storage. If the requested output_format or transcoding settings differ from the uploaded asset, Callaba can start the conversion work that turns the source file into the deliverable the team actually needs.

Examples by preset on this method show the most useful create shapes: preserve an uploaded MP4 as-is, derive an MP3 deliverable, or materialize an HLS package.

Direct asset registration

Use this preset when an uploaded mezzanine file should become a reusable managed asset without additional conversion.

Uploaded MP4 asset

This is the cleanest file-manager path: upload first, then register the asset with metadata, visibility, and a durable file row.

Uploaded MP4 asset

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Save and convert

Use this preset when the stored asset should be rewritten into a simpler audio deliverable during the save flow.

Uploaded file to MP3 derivative

The file row is created first, then the background transcoding worker produces the derivative output and exposes progress through getStat.

Uploaded file to MP3 derivative

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage audio extract",
  "file_visibility": "private",
  "file_description": "Audio-only derivative prepared from the uploaded mezzanine file.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp3",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "mp3",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Segmented output

Use this preset when the resulting asset should be materialized as an HLS package instead of a single file.

Uploaded file to HLS package

This is useful when the managed file will be handed to a playback or delivery workflow that expects an HLS-style directory output.

Uploaded file to HLS package

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage HLS package",
  "file_visibility": "private",
  "file_description": "Segmented HLS output prepared from an uploaded mezzanine file.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "m3u8",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "h264",
    "audio_transcoding": "aac",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Request body parameters

Identity

file_name

string

Dashboard label: Name.

Human-facing asset name stored in the file manager.

Asset path

file_path

string

Dashboard label: File.

Path produced by uploadFile or already known to the platform.

file_unique_id

string

Upload correlation id used to connect an in-progress upload with the saved file row.

Policy

file_visibility

string

Dashboard label: Visibility.

Controls whether the stored file should be treated as public or private in downstream UI flows.

file_description

string

Optional description stored on the file row.

Processing

output_format

string

Dashboard label: Output format.

If the requested format differs from the uploaded extension, the backend starts a background rewrite flow.

transcoding

object

Optional transcoding settings used when the file should be converted into a different deliverable.

Context

module_name

string

Optional source context for UI-driven flows. In practice the file manager most often saves rows under MODULE_FILES.

Create file

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Response

Identity

_id / id / file_name

mixed

Saved file identifiers and the persisted file name.

Asset path

file_path / file_unique_id

mixed

Stored file location plus the upload correlation id.

Policy

file_visibility / file_description

mixed

Saved visibility and descriptive metadata for the asset.

Processing

output_format / transcoding / overlay

mixed

Output-format and processing state stored with the file row.

Runtime

size_bytes / duration_ms / created

mixed

Computed media metrics and backend-managed timestamp fields.

Response: Create file

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/uploadFile

API token required

POST

/api/files/getCount

API token required

POST

/api/files/getAll

API token required

Get all files returns the visible file records for the current filter. Use it when the team needs one inventory view of reusable assets, generated files, or recording outputs that should still be treated as managed media.

Request body parameters

limit

integer

Optional page size for file-manager listing queries.

skip

integer

Optional offset for paginated file listing.

sort

object

Optional sort descriptor. The dashboard defaults to { created: -1 }.

filter

object

Optional filter object. In practice the UI uses this for free-text search and recording-owned subsets.

Get all files

Response

array of file objects

array

The backend returns a bare array of file rows, not a wrapped object.

Response: Get all files

JSON

[
  {
    "_id": "680100000000000000000001",
    "id": "680100000000000000000001",
    "file_name": "Main stage mezzanine",
    "file_unique_id": "file_01abc",
    "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
    "file_path": "uploaded/f-01abc-main-stage.mp4",
    "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
    "storage_id": null,
    "file_visibility": "private",
    "module_name": "MODULE_FILES",
    "entity_name": "",
    "entity_id": null,
    "output_format": "mp4",
    "transcoding": {
      "video_transcoding": "Disabled",
      "audio_transcoding": "Disabled",
      "output_audio_bitrate": 128,
      "sample_rate": 44100
    },
    "overlay": {
      "type": "DISABLED"
    },
    "duration_ms": 612000,
    "size_bytes": 832640000,
    "created": "2026-03-24T18:55:00.000Z"
  }
]

POST

/api/files/getById

API token required

Get file by id loads one saved file record. Use it when a form, picker, or downstream workflow needs the full metadata and processing state for a single asset.

Request body parameters

string

Identifier of the file row you want to inspect.

Get file by id

Response

file object

object

The saved file row including current metadata, media metrics, and processing settings.

Response: Get file by id

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/update

API token required

Update is where the team adjusts a managed asset after it already exists. Simple metadata edits stay lightweight, while format or transcoding changes can also trigger the work needed to reshape the stored file into a better deliverable.

Request body parameters

string

Identifier of the file row being updated.

file payload fields

mixed

The update contract mirrors create and can also trigger a background rewrite when format or transcoding changes.

Update file

curl --request POST \
  --url http://localhost/api/files/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine updated",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "id": "680100000000000000000001"
}'

Response

updated file object

object

The backend returns the updated file row after the save path completes.

Response: Update file

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine updated",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/remove

API token required

POST

/api/files/removeByPath

API token required

POST

/api/files/copyTo

API token required

POST

/api/files/getCopyProgressById

API token required

POST

/api/files/getStat

API token required

Back toRecordings Next toWeb players