Skip to main content

Supported files

If POST /uploads returns 503, do not continue to PUT or verification. Stop the workflow and retry later when instructed, or contact support with the response requestId.
SVG and fonts are not supported by API upload. A file must be valid for its declared type. PDF is stored in Documents; it is not a playable Playlist item. Do not send a PDF as IMAGE or add it to a Playlist.

Create a folder

Send POST /groups with the permission library.groups.create:
Save the returned data.id. Use it as folderId when uploading. If you omit the folder, or it is unavailable or incompatible, the file goes to No group. Use GET /groups to list folders and GET /assets to list files. Both need library.read.

Prepare the file

checksumSha256 is a checksum of your original file, not an API key. See checksum examples. The current upload endpoint also requires sizeBytes. Do not estimate or type the size manually. Use this command to generate a complete request body from the file automatically:
Paste the generated JSON into Postman Body → raw → JSON. To select a folder, add "folderId": "YOUR_GROUP_ID". Set contentType and libraryType to match your file. For MP3, MP4 or PDF, change the file path and the two type fields above. Size and checksum are still calculated from the exact original file. The upload steps below are otherwise identical. Do not provide your own duration, dimensions or verification results: Layarva determines them from the uploaded file.

Upload with Postman

Only step 3, PUT, sends your file. The other requests create the upload session, get upload instructions, or check the result. PUT is not a fixed /uploads API route: its URL is generated for your particular file. That is why it is not listed as a separate fixed endpoint in the API reference.

Step 1: Create the upload session

Create a Postman variable platform_base with this value, replacing YOUR_WORKSPACE_ID:
You need a Platform API key with library.upload. Set Authorization → Bearer Token to your Platform key for requests to platform_base. Send POST {{platform_base}}/uploads:
  • Headers: Content-Type: application/json and Idempotency-Key: YOUR_OPERATION_UUID.
  • Body → raw → JSON: paste the JSON generated in Prepare the file.
Save the returned data.id as the Postman variable upload_id. A 201 response creates the session; it does not mean your file has been uploaded. Use a different Idempotency-Key for each new API operation. Keep the same value when retrying that same operation with the same input.

Step 2: Get the PUT URL

Send POST {{platform_base}}/uploads/{{upload_id}}/capability using your Platform Bearer key:
  • Headers: Content-Type: application/json and a new Idempotency-Key.
  • Body → raw → JSON: {}.
The response contains data.method (PUT), data.url, data.headers, and data.expiresAt. Copy the complete data.url, including its query string, into a Postman variable upload_url. Keep this temporary URL private.

Step 3: Upload the file using PUT

Create a separate Postman request:
  1. Set the method to PUT.
  2. Set the URL to {{upload_url}}, not {{platform_base}}/uploads.
  3. Open Authorization and select No Auth, overriding inherited authorization. Do not send your Platform API key or an Idempotency-Key to this URL.
  4. Open Headers and copy every name and value from data.headers in step 2. Do not change them or calculate the returned checksum header yourself. If Postman automatically adds Content-Type or Content-Length, make sure they match the returned values and avoid duplicate headers.
  5. Open Body → binary → Select File and select the same original file used to prepare the metadata. Do not choose raw JSON or form-data.
  6. Click Send. Continue only after a successful 2xx response. This response may have an empty body; it does not need to contain JSON.
The session expires 15 minutes after step 1. Getting another capability does not extend that deadline. If the session has expired, create a new session. Do not repeatedly PUT after a success: the URL is write-once.

Step 4: Request verification with complete

Send POST {{platform_base}}/uploads/{{upload_id}}/complete:
  • Authorization: your Platform Bearer key again.
  • Headers: Content-Type: application/json and a new Idempotency-Key.
  • Body → raw → JSON: {} — do not attach the file.
This means “I have sent the file; please verify it.” Layarva checks the file before adding it to the Library. A 202 Accepted response means verification was requested, not that verification succeeded. The state may still be RESERVED while verification is waiting to start.

Step 5: Check that the upload succeeded

Send GET {{platform_base}}/uploads/{{upload_id}} with your Platform Bearer key, no body, and no Idempotency-Key.
  • RESERVED or VERIFYING: not ready yet. Check again after a few seconds.
  • COMMITTED: success. Save data.assetId; the file is now available in the Library. Use playable media in a Playlist; PDF remains in Documents.
  • A failureCode, CLEANUP_PENDING, or CLEANED: stop polling and inspect the error. Do not use this upload as a Library asset.
Stop polling if the session expires. Do not keep polling indefinitely. Keep the uploaded file identical to the file used to generate the metadata. Do not edit or recompress it between these steps.

Node.js example

This example uses the request helper from the quickstart. Size and checksum are calculated automatically.

Cancel or delete

  • Cancel an unfinished upload with DELETE /uploads/{id}.
  • Remove an unused file with DELETE /assets/{assetId} and library.delete.
  • A file referenced by published content cannot be removed until those references are no longer in use.