Staticx
Sign in Create account
Agent deployment

Agent Integration Guide

Give an external agent or CI runner a scoped STATICX token, project ID, and deployment contract so it can upload, deploy, and inspect a static site through the API.

Overview Interface guide Quickstart CLI guide Forms API reference Agent guide MCP server Automation

Agent deployment

Give an agent the same release contract your dashboard uses.

Agents should build locally, upload the output ZIP, publish, inspect logs, and return the live URL or the exact API error.

Auth

API token

Contract

/api/v1

Input

ZIP output

Dashboard path

Open Project Settings → Agent deploy.

The project page gives everything an agent needs: project ID, API base URL, current live URL, a generated token flow, the filled text instruction, and MCP config.

Project Agent deploy settings tab.

Recommended setup

Create one scoped token per agent or automation runner.

  1. Create a site token. Use the project Agent deploy tab when the automation only needs one site.
  2. Default to Full access on that site token. It covers upload, deploy, and logs for the site-scoped release flow.
  3. Escalate only when needed. Move to a Workspace token only when the runner truly needs several sites inside one workspace, or to a Global token for broad internal operator flows.
  4. Store it safely. The token is shown once. Put it in the agent environment or secret manager.
  5. Copy the project instruction. The project tab fills in the project ID, base URL, and live URL.
  6. Run the deployment. The agent should build, confirm 404.html, zip, upload, deploy, and verify logs.
  7. Revoke when done. Delete old tokens from the project page or from Settings to remove access.

CLI alternative

Use the public npm CLI when the runner prefers terminal commands.

The site and workspace Agent deploy pages now expose both the text-only agent prompt and a ready-made CLI block with the same token scope. 

npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx whoami
staticx deploy --site-id STATICX_PROJECT_ID --dir dist
staticx logs --site-id STATICX_PROJECT_ID

Scope guide

Use the smallest scope that still lets the agent finish.

Site token

Best default for one build pipeline or one deployment bot tied to a single site.

Workspace token

Use only when one tool must create or update multiple sites inside one workspace. This is the right middle ground between one-site deploy bots and broad account automation.

Global token

Reserve for broad internal tooling or admin-controlled workflows that must cross workspace boundaries, not routine deploy agents.

Copyable instruction

Text-only agent prompt.

Use this format when the agent does not support MCP tools. Replace the token and project ID, or copy the filled version from a project page.

Instruction 
Use the STATICX API to deploy this static website.

API Base URL: https://staticx.site/api/v1
Authentication: Bearer STATICX_API_TOKEN
Project ID: STATICX_PROJECT_ID
Build output directory: dist

Endpoint reference:
- GET /projects/{project} - confirm project state.
- POST /projects/{project}/files - upload the build ZIP with multipart fields mode=zip, overwrite_confirmed=1, and [email protected].
- POST /projects/{project}/deployments - publish a new version.
- GET /projects/{project}/deployments - read deployment history.
- GET /projects/{project}/logs - read project logs.

Steps:
1. Build the project locally.
2. Confirm the build output contains index.html or index.htm plus 404.html at the root.
3. Zip the contents of the build output directory so those root files stay at the ZIP root.
4. Upload the ZIP with POST /projects/{project}/files using mode=zip, overwrite_confirmed=1, and [email protected].
5. Deploy with POST /projects/{project}/deployments.
6. Check GET /projects/{project}/deployments and GET /projects/{project}/logs.
7. Return the live URL or the exact API error message if deployment fails.

Agent rules

What the agent should and should not do.

Do

  • Build the project locally before upload.
  • Make sure index.html or index.htm and 404.html are both at the build output root.
  • Zip the build output contents so those required files are at the archive root.
  • Deploy directly with POST /projects/{project}/deployments after uploading the ZIP.
  • Read deployments and logs before reporting completion.

Do not

  • Do not report success after a failed upload or deployment.
  • Do not guess the output directory if the user gave a specific path.
  • Do not expose tokens in commits, public logs, or screenshots.
  • Do not bypass the documented API contract.