Files API

The Files API lets a workspace token read and write the same Cloud the app shows. A workspace’s documents, sheets, decks, and uploads are Artifacts: one record with a type, a revision history, and provenance you can trace. There is no second machine content service.

Scopes

files.artifacts.read     list, read, search, and trace Artifacts and their revisions
files.artifacts.write    create and edit Artifacts, move, archive, restore, refresh, export
files.records.read       read workspace records and the governed Business Brief
files.records.write      record an inert Business Brief edit proposal

Read and edit a document

POST /v1/tools/artifact_search   { "query": "pricing model" }
POST /v1/tools/artifact_get      { "artifact_id": "…" }
POST /v1/tools/artifact_apply_operation
POST /v1/tools/artifact_export   { "artifact_id": "…", "format": "pdf" }

An edit is an operation against a revision, not a file overwrite, so every change keeps its history and its author. artifact_export renders a format — a PDF of a document, a workbook of a sheet — without leaving the record it came from.

Contracts and the security boundary

The Cloud includes user-uploaded contracts. A category label is editable, so using contracts as an access-control boundary would not protect anything. Separately managed signed-provider documents remain excluded because they live behind signing-specific tables and actions.

Uploads and scanning

Anything a person uploads still goes through the same presign, storage, finalize, and malware-scan path the app uses. Only an explicit clean verdict makes content available. Subscribe to file.available and file.held if your system should be told instead of polling.

AuthenticationWebhooksThe CLI