Documentation menu
Reference

Workspace Files

Entities hold text and structured metadata. Binary attachments — documents, images, video, audio, archives — live in Workspace Files and are referenced from entities by id. Inline base64 in an entity write is refused; upload the bytes instead.

Hosted only (Pro, Team and Enterprise). The self-hosted Platform has no file store.

Uploading a file

1. file_upload_init({ name, mime, size_bytes, sha256?, entity_id? })
     -> { file_id, status: "pending", expires_at, upload }
2. PUT the bytes to upload.url with exactly upload.headers
     (over 100 MB: MULTIPART — PUT each 64 MB part to its parts[].url, keep each ETag)
3. file_complete({ file_id, parts? })   -> status: "ready"
  • Upload URLs expire after 300 seconds; call file_upload_init again if they lapse.
  • file_complete verifies the stored length (and the sha256 on a single PUT). A mismatch deletes the file.
  • Pending uploads that are never completed are removed after 24 hours.

Attaching it to an entity

Reference a ready file in the entity's metadata:

metadata.attachments[] = { file_id, kind: "kvendra-file", title, mime, size_bytes, sha256 }
// a link that is not uploaded:
metadata.attachments[] = { kind: "external-url", url, title }

To show it inside markdown content, cite it as ![alt text](file:<file_id>), and also list it in metadata.attachments[] so it travels with the entity. Attaching a file that is missing, still pending or deleted fails the write with 400 invalid_request. Links to drafts take effect when the transaction is activated.

Downloading and managing files

  • file_get_url({ file_id }) mints a fresh download URL, valid for 300 seconds, on every call. Never store a URL — store the file_id.
  • file_list pages the registry (no URLs), including the live entities that link each file.
  • file_delete removes a file. While it is attached to a live entity it answers 409 file_linked with the entity ids: remove it from metadata.attachments[] first.

Limits

  • At most 500 MB per file. Executables (exe, dll, msi, sh, ps1, jar, apk, …) are refused.
  • Storage quota: 5 GB on Pro; on Team and Enterprise 10 GB for each seat, pooled across the workspace. Files stored by your publications count against the same quota. Exceeding it answers 422 files_quota_exceeded.

Roles

  • Every role can list and download.
  • Owner, admin and member can upload and delete their own files.
  • Owner and admin can delete any file.

Files in publications

When you publish entities, their linked files are preselected. Every published file is a copy with its metadata always stripped (EXIF and GPS, document properties, embedded titles and dates); a file that cannot be cleaned is never published. PDF text is scanned like any other content. Images, video and audio cannot be scanned, so the publisher must confirm each one explicitly before it goes out.