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.Create a folder
SendPOST /groups with the permission library.groups.create:
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:
"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 variableplatform_base with this value, replacing YOUR_WORKSPACE_ID:
library.upload. Set Authorization → Bearer Token to your Platform key for requests to platform_base.
Send POST {{platform_base}}/uploads:
- Headers:
Content-Type: application/jsonandIdempotency-Key: YOUR_OPERATION_UUID. - Body → raw → JSON: paste the JSON generated in Prepare the file.
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/jsonand a newIdempotency-Key. - Body → raw → JSON:
{}.
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:- Set the method to PUT.
- Set the URL to
{{upload_url}}, not{{platform_base}}/uploads. - Open Authorization and select No Auth, overriding inherited authorization. Do not send your Platform API key or an
Idempotency-Keyto this URL. - Open Headers and copy every name and value from
data.headersin step 2. Do not change them or calculate the returned checksum header yourself. If Postman automatically addsContent-TypeorContent-Length, make sure they match the returned values and avoid duplicate headers. - Open Body → binary → Select File and select the same original file used to prepare the metadata. Do not choose raw JSON or form-data.
- Click Send. Continue only after a successful
2xxresponse. This response may have an empty body; it does not need to contain JSON.
Step 4: Request verification with complete
Send POST{{platform_base}}/uploads/{{upload_id}}/complete:
- Authorization: your Platform Bearer key again.
- Headers:
Content-Type: application/jsonand a newIdempotency-Key. - Body → raw → JSON:
{}— do not attach the file.
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.
RESERVEDorVERIFYING: not ready yet. Check again after a few seconds.COMMITTED: success. Savedata.assetId; the file is now available in the Library. Use playable media in a Playlist; PDF remains in Documents.- A
failureCode,CLEANUP_PENDING, orCLEANED: stop polling and inspect the error. Do not use this upload as a Library asset.
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}andlibrary.delete. - A file referenced by published content cannot be removed until those references are no longer in use.

