Documentation

Management API

A small REST API for sites and deployments. The CLI is built on it, so anything the CLI does you can script directly.

Base URL & authentication

http

https://api.mcmanus-ai.com/avoca-mgmt

Send an access token from Account → Access Tokens in the dashboard as a Bearer token. Site endpoints need a token with the sites scope.

shell

$ curl https://api.mcmanus-ai.com/avoca-mgmt/v1/sites \
    -H "Authorization: Bearer avt_…"

Errors are JSON: {"error": "…"}.

Endpoints

Method	Path	What it does
GET	`/v1/sites`	Sites you can view
POST	`/v1/sites`	Create a site
GET	`/v1/sites/:id`	One site (`:id` is the site id, or its slug when unique), with live status
DELETE	`/v1/sites/:id`	Delete a site: removes it from its server (project owner or admin)
GET	`/v1/sites/:id/deployments`	Deploy history
POST	`/v1/sites/:id/deployments`	Start a git build, or get an upload ticket
POST	`/v1/sites/:id/deployments/upload`	Upload a tar.gz in the request body (up to 5 MB)
GET	`/v1/sites/:id/deployments/:deploy_id`	Status of one deploy
GET	`/v1/sites/:id/deployments/:deploy_id/logs?offset=N`	Build log
POST	`/v1/sites/:id/rollback`	Make an earlier deploy live: `{"deploy_id": "…"}`

Create a site

shell

$ curl -X POST https://api.mcmanus-ai.com/avoca-mgmt/v1/sites \
    -H "Authorization: Bearer avt_…" -H "Content-Type: application/json" \
    -d '{"server": "<server id>", "slug": "my-site", "repo_url": "https://github.com/me/my-site", "branch": "main", "framework": "vite"}'

Optional fields: name, repo_url, branch, framework, install_command, build_command, output_dir, root_dir, spa, start_command.

Deploy from git

shell

$ curl -X POST https://api.mcmanus-ai.com/avoca-mgmt/v1/sites/my-site/deployments \
    -H "Authorization: Bearer avt_…" -H "Content-Type: application/json" \
    -d '{"environment": "production", "mode": "git"}'

environment is production or preview; add "ref": "<branch>" to build another branch. The response (202) includes the new deploy; poll GET /v1/sites/:id/deployments/:deploy_id for its status.

Deploy a tarball

Two ways to upload a .tar.gz of your site:

Small archives (up to 5 MB): send it as the body of POST /v1/sites/:id/deployments/upload?environment=production&mode=static. Use mode=static for an already-built folder, or mode=source to build it on the server.
Larger archives: POST /v1/sites/:id/deployments with {"environment": "production", "mode": "upload"} returns a single-use upload_url (valid 10 minutes). PUT the archive there with Content-Type: application/gzip, adding &mode=static or &mode=source.

shell

$ tar -czf site.tgz -C dist .
$ curl -X POST "https://api.mcmanus-ai.com/avoca-mgmt/v1/sites/my-site/deployments/upload?environment=preview&mode=static" \
    -H "Authorization: Bearer avt_…" -H "Content-Type: application/gzip" \
    --data-binary @site.tgz

Roll back

shell

$ curl -X POST https://api.mcmanus-ai.com/avoca-mgmt/v1/sites/my-site/rollback \
    -H "Authorization: Bearer avt_…" -H "Content-Type: application/json" \
    -d '{"deploy_id": "8f2c41a09b"}'

Deploy ids are 10 hex characters.

Delete a site

shell

$ curl -X DELETE https://api.mcmanus-ai.com/avoca-mgmt/v1/sites/my-site \
    -H "Authorization: Bearer avt_…"

Only the project owner or an admin can delete a site. It is removed from its server and from Chapong; this can’t be undone.