# Files API

Source: https://amolfi.com/docs#api--files

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
```

`files.artifacts.read` is a full workspace-content read credential, like granting a Drive or Dropbox integration access to workspace files. Scope it narrowly and revoke it when the integration no longer needs it.

### 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.

Byte transfer is not open to machine tokens yet. A token can list, read, search, create, and edit an Artifact; uploading and downloading raw bytes stays first-party while the public-link rules are settled. Ask us if you need it — the answer is a date, not a workaround.

### 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.

[Authentication](https://amolfi.com/docs/api/authentication)[Webhooks](https://amolfi.com/docs/api/webhooks)[The CLI](https://amolfi.com/docs/api/the-cli)

```
curl https://api.amolfi.com/v1/tools/artifact_search \
  -H "Authorization: Bearer $AMOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"pricing model"}'
```

Requires files.artifacts.read. Read the live OpenAPI schema for the current response contract.