Files & transfer

You talk to Casewelt. Casewelt talks to storage.

There is no “here is a link, put the file there”. You open an upload session, put bytes to Casewelt, and complete. You download by asking Casewelt for a named version. That is the whole data plane, for your store or ours.

Scope files or workspaces (or organisation). Resource permission is still checked: a files token cannot open a workspace it was never granted.

Find the work

	Path	What it does
GET	`/v1/workspaces`	File areas this principal may open.
GET	`/v1/workspaces/{ws}/folders`	Children of a folder, or of the root.
POST	`/v1/workspaces/{ws}/folders`	Create a folder. Send an idempotency key.
GET	`/v1/workspaces/{ws}/files`	Files in a folder.
GET	`/v1/workspaces/{ws}/files/{file}`	Metadata, including current version.
GET	`/v1/workspaces/{ws}/files/{file}/versions`	History you can name later.
GET	`/v1/workspaces/{ws}/search?q=`	Filename search in that workspace.

POST Create a folder

/v1/workspaces/{ws}/folders

The folder belongs to a workspace. There is no orphan /v1/folders. Retry with the same key after a timeout and you do not get a second Board pack.

POST /v1/workspaces/{ws}/folders
Authorization: Bearer …
Idempotency-Key: 7a1f3b…
Content-Type: application/json

{
  "name": "Board pack",
  "parent_folder_id": null
}

Upload a file

Three calls. Quota is checked before bytes are kept. Larger files use multipart: open parts, put each part at most 64 MiB, complete. Abort if you abandon the session. To replace an existing file, send replace_file_id when you open the session.

1 · Open a session

POST /v1/upload-sessions

{
  "workspace_id": "…",
  "folder_id": "…",
  "filename": "pack.pdf",
  "size_bytes": 12000,
  "content_type": "application/pdf"
}

2 · Put the bytes

PUT /v1/upload-sessions/{id}/content

PUT /v1/upload-sessions/{id}/content
Content-Length: 12000

<raw bytes, at most 64 MiB in this PUT>

3 · Complete

POST /v1/upload-sessions/{id}/complete

{ "file_id": "…", "version_id": "…" }

Keep both ids. Shares, signatures and later questions all name a version — not “whatever is latest”.

Download a version

POST /v1/workspaces/{ws}/files/{file}

Follow the transfer. Decrypt happens on Casewelt. Public shares are watermarked; this staff download is not. Other actions on the same path include rename, move, copy, delete, restore, lock, tags, preview, and opening a browser editing session.

POST /v1/workspaces/{ws}/files/{file}
Authorization: Bearer …

{ "action": "content", "version_id": "…" }

{
  "mode": "casewelt_transfer",
  "transfer": { "method": "GET", "path": "/v1/…" }
}

Start a blank document

POST /v1/documents

Creates a governed file (Word, spreadsheet, presentation, OpenDocument, text, CSV). It is not assistance. List templates first with GET /v1/documents?workspace_id=.

{
  "workspace_id": "…",
  "folder_id": "…",
  "title": "Board minutes",
  "format": "word"
}

Calendar, inbox, inbound requests

Path	What it is for
`/v1/calendar/events`	Share expiries, signature due dates, notes and reminders.
`/v1/activity` · `/v1/notifications`	What changed, what is waiting on this principal.
`/v1/file-requests`	Create a public drop into a folder. The recipient uses the public file-request door, not your Bearer token.