8.4The REST API

Sync, upload, commit, list versions, and restore, authenticated with a project key.

Section 4 of 4 in this chapter

Everything the desktop app does over the network, it does through a documented REST API you can call yourself. Requests authenticate with a project key and are scoped to that key's project — a key cannot reach a project it was not issued for, no matter what id you put in the path.

The natural uses are the ones that do not fit a desktop app: onboarding a machine from a script, pulling a specific revision inside somebody else's CI, wiring a build agent that is not Forge, or exporting your own data on your own schedule.

The shape of an upload

Uploads are three steps rather than one, because the bytes never pass through our application servers: you reserve a version and get a presigned URL, you PUT the file straight to storage, and you confirm. The commit then references the versions you created.

   you                 api                 storage
    │                   │                     │
    ├── initiate ──────►│                     │
    │◄── presigned url ─┤                     │
    │                                         │
    ├── PUT bytes ───────────────────────────►│
    │                                         │
    ├── confirm ───────►│                     │
    │                   │                     │
    ├── commit ────────►│  { fileId, version }│

Figure 8-1. Uploading a file through the API. The bytes go direct to storage.

The full endpoint reference, with curl and TypeScript for every call, is Appendix A.

Was this helpful?