> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layarva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Files and Manage Library Folders

> Create folders, upload files and remove unused Library assets.

## Supported files

| File | Maximum size | Library section |
| - | - | - |
| PNG, JPEG, WebP, GIF, AVIF | 32 MiB | MEDIA, IMAGE or BACKGROUND |
| PCM WAV | 16 MiB | MEDIA or AUDIO |
| Self-contained Lottie JSON | 2 MiB | MEDIA or LOTTIE |
| MP3 (`audio/mpeg`) | 32 MiB | MEDIA or AUDIO |
| MP4 (`video/mp4`) | 128 MiB | MEDIA or VIDEO |
| PDF (`application/pdf`) | 32 MiB | DOCUMENTS only |

> [!NOTE]
>
> 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`:

```json theme={null}
{
  "name": "Lobby images",
  "libraryType": "IMAGE"
}
```

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](https://docs.layarva.com/developers/platform-request-keys.md).

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:

```powershell theme={null}
$file = Get-Item -LiteralPath "C:\Media\poster.png"
@{
  fileName = $file.Name
  contentType = "image/png"
  checksumSha256 = (Get-FileHash -LiteralPath $file.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
  sizeBytes = $file.Length
  libraryType = "IMAGE"
} | ConvertTo-Json
```

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.

| Request | Purpose | Sends the file? |
| - | - | - |
| `POST /uploads` | Create an upload session and return its `id` | No |
| `POST /uploads/{id}/capability` | Get a temporary URL and the headers for PUT | No |
| `PUT` to the returned `data.url` | Send the original file as binary | **Yes** |
| `POST /uploads/{id}/complete` | Ask Layarva to verify the uploaded file | No |
| `GET /uploads/{id}` | Check whether the file is ready in the Library | No |

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`:

```text theme={null}
https://api.layarva.com/api/platform/v1/workspaces/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](#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](https://docs.layarva.com/developers/platform-request-keys.md) 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](https://docs.layarva.com/developers/platform-quickstart.md). Size and checksum are calculated automatically.

```javascript theme={null}
import { readFile } from "node:fs/promises";
import { createHash, randomUUID } from "node:crypto";

const bytes = await readFile("./poster.png");
const reserveKey = randomUUID(); // Save and reuse if this request is retried.
const { data: upload } = await platform("POST", "/uploads", {
  fileName: "poster.png",
  contentType: "image/png",
  checksumSha256: createHash("sha256").update(bytes).digest("hex"),
  sizeBytes: bytes.length,
  libraryType: "IMAGE"
}, reserveKey);

const capabilityKey = randomUUID();
const { data: instructions } = await platform(
  "POST", `/uploads/${upload.id}/capability`, {}, capabilityKey
);
const sent = await fetch(instructions.url, {
  method: instructions.method,
  headers: instructions.headers,
  body: bytes,
  redirect: "error"
});
if (!sent.ok) throw new Error("File upload failed");

const completeKey = randomUUID();
await platform("POST", `/uploads/${upload.id}/complete`, {}, completeKey);
// Check GET /uploads/{id} until COMMITTED before using the asset.
```

## 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.

## Related guides

* [API keys](https://docs.layarva.com/developers/platform-api-keys.md)
* [Idempotency-Key and checksums](https://docs.layarva.com/developers/platform-request-keys.md)
* [Create and publish a Playlist](https://docs.layarva.com/developers/platform-playlists-publication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.