# Automation

> Practical patterns for internal dashboards, CI jobs, and operational tooling built on the current route set.

Canonical: https://staticx.site/documentation/automation

Automation patterns

## One route set, several operating surfaces.

 Use the same API contract for CI/CD, internal dashboards, agent deployments, and partner workflows. The key is to keep release state visible: upload, choose history mode, deploy, verify logs.

 

  Use cases

## Where automation fits.

 

### CI/CD releases

Build a project in CI, confirm `index.html` and `404.html`, zip the output, upload it, deploy, and report the public URL.

 

### Customer dashboards

Let customers create sites, see deployment history, and read activity logs from a branded portal.

 

### AI agents

Give an agent a token and project ID, then let it deploy generated static sites through the API or MCP tools.

 

 

  Release recipe

## The minimum reliable sequence.

 

 ```
1. Build the website locally or in CI.
2. Confirm index.html or index.htm and 404.html are at the output root.
3. Zip the contents of the output directory so those files are at the archive root.
4. POST /api/v1/projects/{project}/files with mode=zip, overwrite_confirmed=1, and archive=@site.zip.
5. If the upload returns status=queued, poll GET /api/v1/projects/{project}/imports/status until state=completed.
6. POST /api/v1/projects/{project}/deployments.
   Optional: send {"versioning_enabled":false} when the workflow should update one baseline release instead of creating rollback history.
7. GET /api/v1/projects/{project}/deployments.
8. GET /api/v1/projects/{project}/logs.
9. Return the live URL or the exact API error.
```

  Operational rules

## Make automation boring and debuggable.

 

### Token policy

 Use a separate token per CI job, customer dashboard, or agent. Default to a **Site** token with **Full access** for one-site release jobs, move up to a **Workspace** token only when one tool truly needs several sites, and reserve **Global** tokens for broad internal operator workflows.

 

### Error policy

 Treat non-2xx responses as failures. Read logs before retrying. Do not return success unless the API confirms the upload and deployment.

 

### Workspace policy

 Keep projects inside the correct workspace. Use workspace IDs when automation needs to create sites for a specific team or client.

 

### Alert policy

 Let deployment failures land in the notification inbox and, for critical flows, also in email. Use the inbox as the shared timeline when debugging release issues.

 

### Archive policy

 Zip the output contents directly. Avoid nested archives where the first folder contains the actual `index.html` and `404.html`.

[View on staticx.site](https://staticx.site/documentation/automation)