# Content Workflows

## Table of Contents

- Upload a file
- Create folders
- List folder items
- Download or preview a file
- Generate a shared link
- Invite collaborators
- Move a file or folder
- Read or write metadata

Read `references/auth-and-setup.md` first when the acting identity or SDK vs REST choice is unclear.

For local or manual verification, prefer native Box CLI commands when Box CLI is available and authenticated. Use direct REST only as a last resort after MCP/CLI setup attempts and explicit user confirmation.

## Upload a file

- Primary docs:
  - https://developer.box.com/reference/post-files-content/
- Use for local-disk uploads, form uploads, or pushing generated artifacts into Box.
- Decide whether the input is a file path, in-memory upload, or generated artifact.
- Set the destination folder ID first.
- Treat file-name conflicts explicitly.
- Start with standard upload; use chunked upload only when file size or resumable behavior requires it.
- When building raw multipart REST uploads, sanitize filenames used in `Content-Disposition` headers (escape quotes and backslashes; strip CR/LF) to avoid malformed requests and header-injection edge cases.
- Minimal smoke check:
  - Upload the file, then list the destination folder with the same actor and confirm returned `id` and `name`.

## Create folders

- Primary docs:
  - https://developer.box.com/reference/post-folders/
- Use for customer, project, case, employee, or workflow roots.
- Decide the parent folder and canonical naming scheme before coding.
- Handle duplicate-name conflicts intentionally.
- Persist the returned folder ID instead of reconstructing paths later.
- Minimal smoke check:
  - Create the folder, then list the parent folder and confirm the child folder ID and name.

## List folder items

- Primary docs:
  - https://developer.box.com/reference/get-folders-id-items/
- Use for dashboards, file pickers, sync views, or post-upload verification.
- Request only the fields the app actually needs.
- Handle pagination instead of assuming a single page.
- Filter server-side where practical before adding client-side transforms.
- Minimal smoke check:
  - Read the folder with a limited field set and confirm the app can process pagination metadata.

## Download or preview a file

- Primary docs:
  - https://developer.box.com/reference/get-files-id-content/
  - https://developer.box.com/guides/embed/ui-elements/preview/
- Download when the app truly needs raw bytes for processing or export.
- Use preview patterns when the app needs an embedded viewer.
- Preserve filename, content type, and auth context in tests and logs.
- Minimal smoke check:
  - Fetch the file metadata first; only then download or preview the exact file ID you intend to use.

## Generate a shared link

- Primary docs:
  - https://developer.box.com/reference/put-files-id/
  - https://developer.box.com/reference/put-folders-id/
- Use for external sharing, customer handoff, or quick verification outside the app.
- Add or update `shared_link` on the target file or folder, not on an unrelated object.
- Set access level, download permissions, and expiration intentionally.
- Confirm the user explicitly wants the audience widened before enabling or broadening sharing.
- Minimal smoke check:
  - Read the file or folder after the update and confirm the resulting `shared_link` fields.

## Invite collaborators

- Primary docs:
  - https://developer.box.com/reference/post-collaborations/
- Use for team, vendor, or customer access to a shared workspace.
- Prefer folder collaboration when multiple files should inherit the same access.
- Choose the narrowest role that satisfies the request.
- Verify the acting identity is allowed to invite collaborators before coding the flow.
- Minimal smoke check:
  - Create the collaboration, then fetch or list collaborations to confirm the collaborator and role.

## Move a file or folder

- Primary docs:
  - https://developer.box.com/reference/put-files-id/ (update parent to move a file)
  - https://developer.box.com/reference/put-folders-id/ (update parent to move a folder)
- Use for reorganizing content, filing into project or category folders, or migrating between folder structures.
- A move is a PUT on the item that sets `parent.id` to the new folder.
- Moving a folder moves all of its contents recursively.
- Handle name conflicts in the target folder — Box returns `409` if a same-named item already exists in the destination.
- For bulk moves (more than a handful of items), read `references/bulk-operations.md` for the inventory-plan-execute-verify workflow, serial execution constraints, and rate-limit handling.
- Minimal smoke check:
  - Move the item, then list the target folder and confirm the item appears with the correct ID and name. Also list the source folder to confirm the item is gone.

## Read or write metadata

- Primary docs:
  - https://developer.box.com/reference/post-files-id-metadata-global-properties/
- Use for invoice IDs, customer names, case numbers, review states, or other business context.
- Read the template definition or existing metadata instance before writing values.
- Keep template identifiers and field names in config, not scattered through the codebase.
- Validate keys and value types in code before calling Box.
- Minimal smoke check:
  - Write the metadata, then read the same instance back and confirm only the expected keys changed.