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

# Workspace assets

> Version files with your workspace, serve them per environment, and control who can read them with folders, access levels, organization and group bindings, labels, and security rules

> [!NOTE]
>
> Introduced in v27.11.0.

Workspace assets are files that live inside the workspace folder, next to its automations, pages, and security rules. They are versioned with the workspace: they travel in workspace exports and imports, in Git pushes and pulls, and in deploys to another environment. The published pages of a workspace, their sources, and any file you add yourself are all assets.

Assets are different from [uploads](https://docs.prisme.ai/products/ai-builder/files.md), which are runtime files (documents produced by an automation, files uploaded by end users) that stay in the environment where they were created.

| | Assets | Uploads |
| - | - | - |
| Builder location | **Files** > **Assets** | **Files** > **Uploads** |
| Identity | The path you choose, such as `img/logo.png` | A generated id |
| Versioned, exported, pushed to Git | Yes | No |
| Storage | The workspace storage (`WORKSPACES_STORAGE_*`) | The uploads storage (`UPLOADS_STORAGE_*`) |
| Access | `private` (with organization and group bindings), `authenticated`, or `public`, plus security rules | Public or private file, signed URL |
| API | `/v2/workspaces/{workspaceId}/assets` | `/v2/workspaces/{workspaceId}/files` |

## Folders and default access

An asset path is relative to the workspace `assets/` folder. The folder an asset lives in sets its default access:

| Folder | Content | Default access |
| - | - | - |
| `src/` | Page sources saved by the Builder page editor (for example `src/src/App.tsx`) | `private` |
| `dist/app/` | The published app bundle (`dist/app/bundle.js`) | The access chosen when the pages were last published, `private` if they were never published |
| `dist/public/` | The prerendered public pages, their hydration script, and `sitemap.xml` | `public` |
| Any other path | Files you add yourself, such as images or fonts | `private` |

The Builder writes `src/`, `dist/app/`, and `dist/public/` when you save and [publish pages](https://docs.prisme.ai/products/ai-builder/deployment.md#publish-pages). Keep your own files in other folders, such as `img/` or `fonts/`: a publish replaces the files of these three folders, and removes the files of `dist/public/` it did not write.

## Access levels

Each asset has one access level, its folder default unless you set another one:

| Access | Who can read the asset |
| - | - |
| `private` | Members of the workspace, and the organizations and groups of its [bindings](#share-a-private-asset-with-organizations-and-groups). Owners and editors can also upload, update, and delete it, viewers can only read it. |
| `authenticated` | Any signed-in user, whatever its organization. Visitors without a session and anonymous sessions are refused. |
| `public` | Anyone, including visitors without a session. |

The workspace [security rules](#open-assets-with-security-rules) can grant more access on top of these levels.

## Share a private asset with organizations and groups

A `private` asset can be read by the organizations and groups listed in its bindings, besides the workspace members:

| Binding | Who can read the asset |
| - | - |
| `{ principalType: org, principalId: acme }` | The members of the `acme` organization, whatever their active organization |
| `{ principalType: org, principalId: '*' }` | The members of any organization |
| `{ principalType: group, principalId: 'acme:sales' }` | The members of the `sales` group of the `acme` organization, while `acme` is their active organization |

Bindings use the same principals as the bindings of the runtime [access manager](https://docs.prisme.ai/products/ai-builder/module-access-manager.md#product-bindings-functions). They only match signed-in users: an anonymous session of an organization, such as a visitor of a public chat widget, never matches a binding of this organization. They are not evaluated on an `authenticated` or `public` asset, which is already readable by more users, and they only grant reading.

A user can only share with their own organizations and their groups: another organization, or `*` (every organization), is refused with `403`, unless the platform allows cross-organization sharing (`ALLOW_CROSS_ORG_SHARING`, see [Environment variables](https://docs.prisme.ai/self-hosting/kubernetes/environment-variables.md)). Platform superadmins share with any organization. The bindings an asset already has are kept, whoever added them: changing its access or labels never fails on them.

In the Builder, add bindings in **Shared with organizations and groups**: select **Group** then one of the groups of your active organization, or **Organization** then one of your organizations (a platform superadmin can pick any organization, or **Every organization**). The binding is added as soon as you pick it; remove it with the cross next to it.

### Require a permission of the organization roles

A private asset with bindings can also require an organization permission (`orgPermission`), named by the workspace `<subject>:<action>` (for example `reports:read`): only the members of its organizations and groups whose organization role grants `ws:<workspace slug>:<subject>:<action>` read it. The permission comes from the role of the active organization of the user, and only counts when this organization is one of the bindings. In the Builder, type it in **Permission also required**, under the bindings: the field shows the full name to grant in a role of **AI Governance**. See [Require a permission of the organization roles](https://docs.prisme.ai/products/ai-builder/rbac.md#require-a-permission-of-the-organization-roles) for the wildcards and the rules on its name.

Bindings belong to the environment that sets them. They are exported with the asset, so a pre-production and a production environment with the same organizations share them without setting them twice, but an import never replaces the bindings an environment already has for an asset. See [Versioning, export, and import](#versioning-export-and-import).

A request for an asset the caller cannot read returns `404`, not `403`, so that the existence of a restricted path is not disclosed. The published app (`dist/app/`) is the exception: its URL is the app's, so an existing file of the app the caller cannot read returns `403`, and the platform asks an anonymous visitor to sign in and tells a signed-in user the app is not shared with them.

## Upload an asset from the Builder

1. In Builder, open the workspace and select **Files** in the sidebar.
2. Select the **Assets** tab.
3. Select **Upload an asset** and choose a file. The **Upload an asset** dialog opens.
4. In **Path**, enter the location of the file in the workspace assets, for example `img/logo.png`. An asset already at this path is replaced.
5. In **Who can read this asset?**, select **Folder default**, **Private**, **Signed-in users**, or **Public**. **Folder default** shows the access it gives at this path. These are the same choices as for [publishing pages](https://docs.prisme.ai/products/ai-builder/deployment.md#publish-tab).
6. Optional: in **Shared with organizations and groups**, add the organizations and groups that can read the asset while it is private.
7. Optional: in **Labels**, enter comma-separated labels, for example `partners, brand`. Security rules can match them.
8. Select **Upload**. The asset appears in the list with its access and its labels.

To verify the access, select the open icon on the asset row to get its URL, then open this URL in a private browser window: a `public` asset is displayed, a `private` or `authenticated` asset returns `404`.

To delete an asset, select the trash icon on its row, then select it again to confirm.

## Change the access of an asset from the Builder

1. In **Files** > **Assets**, select the shield icon on the asset row. The **Asset access** dialog opens on the current access of the asset: an asset that follows its folder default shows the access of its folder. The icon is shown only to the users who can update the asset.
2. In **Who can read this asset?**, select **Folder default**, **Private**, **Signed-in users**, or **Public**. Select **Folder default** to remove an access set on the asset.
3. If the asset is private, change the organizations and groups in **Shared with organizations and groups**. When the asset becomes **Signed-in users** or **Public**, its organizations and groups are kept, and apply again if it becomes private.
4. Optional: change its **Labels**.
5. Select **Save**. The asset row shows its new access. The file itself is not uploaded again.

## Asset metadata files

An asset that has an access other than its folder default, bindings, labels, or free metadata gets a metadata file next to it, named `<asset path>.meta.yml`:

```yaml theme={null}
# assets/img/logo.png.meta.yml
sharing: private
bindings:
  - principalType: org
    principalId: acme
orgPermission: brand:read
labels:
  - brand
```

The metadata file is versioned and exported with its asset. It is written only when it holds something, removed when the asset gets back to its defaults, and deleted with its asset. The `.meta.yml` suffix is reserved: you cannot upload an asset whose path ends with it, and a metadata file is never served or listed. A metadata file that cannot be read, or with an unknown `sharing` value, makes its asset `private`, even in `dist/public/`.

## Serve assets

An asset is served at:

```
https://<api-host>/v2/workspaces/<workspace-slug>/assets/<path>
```

`<workspace-slug>` can also be the workspace id. Because the URL is built from the environment API host and the workspace slug, the same relative path, such as `assets/img/logo.png`, resolves in every environment the workspace is deployed to.

The response depends on the asset:

* Its `Content-Type` comes from its file extension. An unknown extension is served as `application/octet-stream`.
* Every response carries `X-Content-Type-Options: nosniff`.
* HTML, SVG, and XHTML files are served with a sandboxing `Content-Security-Policy`: they never get the session of their visitor, see [Prerendered pages and the visitor session](https://docs.prisme.ai/products/ai-builder/deployment.md#prerendered-pages-and-the-visitor-session). Outside `dist/public/`, HTML, SVG, XHTML, and XML files are served as downloads (`Content-Disposition: attachment`).
* `public` assets can be cached by shared caches (`Cache-Control: public, max-age=300, s-maxage=600, stale-while-revalidate=86400`). Other assets are never cached by shared caches (`Cache-Control: private, max-age=0, must-revalidate`).
* Except prerendered pages, assets are served with an `ETag` and a `Last-Modified` date, and a conditional request for an unchanged asset returns `304`.
* An asset that is not `public`, requested as a script or a stylesheet by another site, is answered with `Cross-Origin-Resource-Policy: same-site`: the browser refuses to run it, so another site cannot read it with the session of a signed-in visitor. Images, fonts, and `fetch()` calls are not affected, so the platform and custom domains can still embed restricted images.

### Page URLs in `dist/public/`

The prerendered pages of `dist/public/` are served with clean URLs:

* A URL that ends with `/` serves the `index.html` file of this folder: `.../assets/dist/public/about/` serves `dist/public/about/index.html`.
* A URL without extension and without a final `/`, such as `.../assets/dist/public/about`, is redirected with `301` to the same URL with a final `/` (a relative `Location`, such as `about/`), its query string kept, when the caller can read the `index.html` file of this folder. It returns `404` otherwise.

In `dist/public/sitemap.xml`, the `{{SITE_URL}}` placeholder written by the Builder is replaced on each request with the URL of `dist/public/` built from the `API_URL` of the environment, so the same sitemap is valid in every environment. Without `API_URL`, the URLs of the sitemap are relative.

### Assets of a published app

When a workspace is published as an app, each app version gets a copy of the assets it serves: the deployed app (`dist/app/`) and the configuration block, with their metadata files. Sources, uploads, and the site are not copied. The configuration UI of an app can then be one of its assets: set the `config.block` of the workspace to its relative path, such as `assets/dist/public/config.js`. It must be a single self-contained file: the files next to it are not copied with the app. In the workspaces that install the app, this path resolves to the copy published with the installed app version:

```
https://<api-host>/v2/apps/<app-slug>/assets/<path>?version=<app-version>
```

Without `version`, the latest published version is served. Publishing the workspace again changes nothing for the installed apps until the app itself is published again. Only the versions listed in the app are served: a version dropped from the list (beyond the limit of versions kept per app) is removed from the storage, and the instances installed with it can no longer be updated.

The access of the published copy is the one the asset had when the app version was published, and the [security rules](#open-assets-with-security-rules) and roles of the source workspace apply. A user of an installed app who is no collaborator of the source workspace only gets the assets it shares: put the configuration UI in `dist/public/`, or give it the `authenticated` access or bindings. The route requires a signed-in user, and serves the asset with the same headers as above.

## Manage assets with the API

Every route takes the workspace id in `{workspaceId}`, and requires a session or an API key, except for serving `public` assets.

| Operation | Route | Notes |
| - | - | - |
| Upload | `POST /v2/workspaces/{workspaceId}/assets` | `multipart/form-data`. Send one `file` part per file, with a `path` field per file (the file name by default). Optional `sharing` (`private`, `authenticated`, or `public`), `bindings` (a JSON array of bindings, or one array per file), `orgPermission` (the organization permission the bindings must also have, `null` to remove it; one per file), `labels` (a JSON array of strings), and `metadata` fields. A field you omit keeps the current value of an existing asset. |
| List | `GET /v2/workspaces/{workspaceId}/assets?prefix=img/` | Returns the assets the caller can read, with their path, size, date, access, labels, and `canUpdate`, whether the caller can change the asset. The bindings are only returned to the callers who can update the asset. |
| Change access, bindings, labels, or metadata | `PATCH /v2/workspaces/{workspaceId}/assets/{path}` | JSON body with `sharing` (`null` restores the folder default), `bindings`, `orgPermission` (`null` removes it), `labels`, and `metadata`. The file is not uploaded again. A binding that is neither an organization nor a group is refused with `400`. |
| Delete | `DELETE /v2/workspaces/{workspaceId}/assets/{path}` | Deletes the asset and its metadata file. |
| Serve | `GET /v2/workspaces/{workspaceId}/assets/{path}` | See [Serve assets](#serve-assets). |
| Serve from a published app | `GET /v2/apps/{appSlug}/assets/{path}?version=` | See [Assets of a published app](#assets-of-a-published-app). |

```bash theme={null}
curl -X POST "https://api.example.com/v2/workspaces/<workspace-id>/assets" \
  -H "Authorization: Bearer <token>" \
  -F file=@logo.png \
  -F path=img/logo.png \
  -F sharing=public \
  -F 'labels=["brand"]'
```

Replace `<workspace-id>` with the id of the workspace and `<token>` with a session token or an API key of a workspace owner or editor.

An upload accepts files up to `ASSETS_MAX_SIZE` (20 MB by default) whose type is allowed by `ASSETS_ALLOWED_MIMETYPES` (text, JavaScript, JSON, XML, images, and fonts by default). Both are set by the platform administrator, see [Configuration > Upload and request limits](https://docs.prisme.ai/self-hosting/kubernetes/configuration.md#upload-and-request-limits).

## Asset events

Each change made through the API emits an event in the workspace, that an automation can listen to:

| Event | Emitted when | Payload |
| - | - | - |
| `workspaces.assets.uploaded` | Files are uploaded | `assets`: the path, size, mimetype, access, bindings, and labels of each uploaded file |
| `workspaces.assets.updated` | The access, bindings, labels, or metadata of an asset change | `asset`: the path, size, mimetype, access, bindings, and labels of the asset |
| `workspaces.assets.deleted` | An asset is deleted | `path`: the path of the asset |

The payload also carries the `userId` of the caller when the caller is a user. The events can be read by everyone who can read the workspace events, by default its owners and editors, bindings included. Imports, pulls, and rollbacks do not emit one event per asset.

## Open assets with security rules

The workspace security rules apply to assets through the `assets` subject. A rule can match any of these asset fields:

| Field | Value |
| - | - |
| `path` | The asset path, for example `img/logo.png` |
| `folder` | `src`, `dist/app`, `dist/public`, or the first segment of the path for any other asset |
| `name` | The file name |
| `mimetype` | The type derived from the file extension |
| `sharing` | `private`, `authenticated`, or `public` |
| `bindings` | The organization and group bindings of the asset |
| `orgPermission` | The organization permission its bindings must also have, if any |
| `labels` | The asset labels |
| `metadata` | The free metadata of the asset |

For example, this rule lets anyone, including visitors without a session, read the assets labelled `partners`:

```yaml theme={null}
authorizations:
  rules:
    - action: read
      subject: assets
      conditions:
        labels:
          $in:
            - partners
```

A rule can also be restricted to some callers with a `user` condition, matched on the signed-in user. For example, this rule lets the signed-in members of the `acme` and `partner` organizations, never their anonymous sessions, read the assets labelled `partners`:

```yaml theme={null}
authorizations:
  rules:
    - action: read
      subject: assets
      user:
        authProvider:
          $ne: anonymous
        orgSlugs:
          $in:
            - acme
            - partner
      conditions:
        labels:
          $in:
            - partners
```

See [RBAC > Restrict a rule to some users](https://docs.prisme.ai/products/ai-builder/rbac.md#restrict-a-rule-to-some-users) for the user fields a rule can match.

A rule always applies to the assets of its own workspace only. An inverted rule without a `role` applies to every user, the workspace owners included. See [RBAC](https://docs.prisme.ai/products/ai-builder/rbac.md#subjects-and-actions) for the actions of the `assets` subject.

## Versioning, export, and import

Assets and their metadata files are part of the workspace version:

* A workspace export contains them under `assets/`, and pushing to Git commits them with the rest of the workspace.
* Importing an archive adds and replaces assets, and never deletes one. Importing with **Prune**, pulling from a repository, and rolling back to a version also delete the assets that are absent from the source.
* A source exported before workspace assets existed, such as an old archive, an old commit of a repository, or an old version, never deletes an asset: its import, pull, or rollback keeps all the assets of the workspace, the published app included, and returns an `AssetsKept` warning. A source exported since then deletes the assets it does not contain, even when it contains none.
* An import, a pull, and a rollback bring the access, labels, and metadata of each asset, but never replace the bindings an asset already has in the target environment, even an empty list, nor the permission that goes with them. Bindings from the source, and their permission, are only applied to assets without bindings yet. A prune keeps the bindings, and their permission, of the assets that stay.
* An imported asset bigger than `ASSETS_MAX_SIZE`, or whose known file type is not allowed, is skipped: it is missing from the list of imported files, and the copy already in the workspace, if any, is kept.
* The `exclude` setting of a repository pull does not apply to assets.

See [Versioning](https://docs.prisme.ai/products/ai-builder/versioning.md#whats-versioned) for the rest of the workspace version.

## Troubleshooting

### An asset URL returns `404`

The asset does not exist at this path, or the caller cannot read it. Check the path in **Files** > **Assets**, then its access: a `private` asset requires a workspace role or a matching [binding](#share-a-private-asset-with-organizations-and-groups), and an `authenticated` asset a signed-in user. To share it, change its access, add a binding, or add a [security rule](#open-assets-with-security-rules).

### The app says "You don't have access to this app"

The bundle of the published app (`dist/app/`) returned `403`: the signed-in user is neither a workspace collaborator nor in an organization or group the app is shared with. Change its access in **Publish**, or add the user's organization or group to its bindings.

### A public asset is still readable after it was made private

`public` assets can be kept by shared caches, such as a CDN in front of the API, for 10 minutes (`s-maxage=600`), then served stale for up to a day while they revalidate (`stale-while-revalidate=86400`): the first request after these 10 minutes can still get the cached copy. Purge the CDN cache for this URL if the asset must disappear at once.

### `'*.meta.yml' is reserved for asset metadata`

The upload path ends with `.meta.yml`. Choose another path: metadata files are written by the platform.

### `size must not exceed` or `mimetype must be one of`

The file is bigger than `ASSETS_MAX_SIZE`, or a type is not allowed by `ASSETS_ALLOWED_MIMETYPES`: the type sent with the file, or the type of its path extension, the one it is served with. Ask the platform administrator to raise the limit or to allow the type. A path with an unknown extension is only checked on the type sent with the file, and is served as `application/octet-stream`, as a download.

### An HTML file is downloaded instead of displayed

Outside `dist/public/`, HTML, SVG, XHTML, and XML assets are served as downloads, so that an uploaded document cannot run in the API domain. Publish pages from the Builder to serve them as web pages.

### `bindings must be an array of { principalType: org | group, principalId }`

A binding is neither an organization (a slug, or `*`) nor a group (`organization:group`). Bindings cannot target a single user: share the asset with its organization or one of its groups, or give the user a workspace role.


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