Frontend workers REST API
Every path starts with ${TARUVI_SITE_URL}/api/cloud/frontend_workers/.
Authenticate with Authorization: Api-Key TARUVI_API_KEY.
Workers#
| Method | Path | Purpose |
|---|---|---|
GET | / | List workers |
POST | / | Create a worker; send a multipart file to deploy a build at the same time |
GET | /{slug}/ | Read one worker, including web_url |
PATCH | /{slug}/ | Rename the worker, change subdomain_input, or upload a new build as a multipart file |
DELETE | /{slug}/ | Delete the worker |
PATCH | /{slug}/set-active-build/ | Make a finished build live: {"build_uuid": "BUILD_UUID"} |
GET | /check-subdomain-availability/?subdomain= | Check whether an address is free; exclude_slug skips a worker's own address |
GET | /{slug}/builds/{build_uuid}/download/ | Download a build's archive |
POST and PATCH with a file also accept set_active=true to record that
build as live. Either way, an upload replaces the files served at the worker's
address; set_active only changes which build is recorded as live. A worker's
first build goes live automatically. set-active-build redeploys a build from
its archive, so use it only with builds uploaded as .zip: for a .tar,
.tar.gz, or .tgz build it removes the live files and then fails. The slug
can't be changed after creation.
Builds#
| Method | Path | Purpose |
|---|---|---|
GET | /{slug}/builds/ | List the worker's builds, newest first |
GET | /{slug}/builds/{build_uuid}/ | Read one build |
DELETE | /{slug}/builds/{build_uuid}/ | Delete a build that isn't live |
Builds are created by uploading a file to the worker, not by posting to
builds/. See Upload a new version.
Archive limits#
| Rule | Value |
|---|---|
| Maximum archive size | 10 MiB |
| Required file | index.html at the archive root |
| Not allowed | .env files at the archive root |
| Formats | .zip, .tar, .tar.gz, .tgz (the Console accepts .zip only) |
Archives and deployment#
Frontend workers serve static sites packaged as one archive:
- Run your framework's production build, such as
npm run build. - Zip the contents of the output folder (the folder that contains
index.html), not the whole repository. - Upload it, then make it live when you're ready.
Anything in the archive is public once it's live. Never include API keys, database passwords, or other secrets in the build.
Security and access#
- Listing and reading workers and builds needs any signed-in user of the site.
- Creating, changing, and deleting workers, uploading builds, changing the live
build, and deleting builds need an organization owner or admin, or another
cloud user with access to the site. Other users get
403 Forbidden. - TaruviBase rejects archives with a
.envfile at the root, or unsafe paths such as../.
Before automating deploys, test one allowed and one denied account. There's no published limit on the number of workers; if you plan to run many, contact TaruviBase support.