PermuteDocs
Go to Permute

Apps · appsSiteUpdate

Save app source and an optional compiled site

Requires app write permission, a complete source manifest with build instructions, and the expected draft ref. Verifies uploaded source and optional compiled files before saving one App revision. Omit site to checkpoint source without replacing the previous build. Supply site to declare that its files were compiled from this exact source; the server records the build input hash. Publication rejects a build whose hash does not match current source. Compiled sites require index.html and relative asset URLs (Vite base ./); use spa=true for HTML navigation fallback. Source allows 1,000 files; compiled sites allow 200. Each manifest allows 4 MiB per file and 50 MiB total. Optional source-file executable flags preserve script permissions. Exclude credentials, local agent state, dependencies, caches and compiled output from source. Optional actions pin published action revisions; omission preserves bindings and [] clears them. Publication requires current invocation permissions and app grants. No compilation or publication occurs here.

PUT/v1/apps/{applicationId}/site
betaapiKeyworkspace

When to use

Checkpoint source or save source and its compiled output together.

For agents

Use the draft ref read before editing; a conflict requires reconciliation. Include complete source and build instructions (including lockfiles and config). Omit site to checkpoint source; supplying site declares it was compiled from that source. Publication requires a matching build and current app grants. Optional actions pins published revisions; omission preserves bindings and [] clears them. Build locally with relative asset URLs. Save does not publish: use client.revisions.publish with the version token returned by revisions.list, checking that its draft matches your saved revision.

Example

typescript
import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.apps.saveSite('appl_abcdefghijklmnopqrstuvwx', {
  "source": {
    "files": [
      {
        "path": "src/main.tsx",
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "size": 1024
      }
    ],
    "build": {
      "command": "bun run build --base=./",
      "outputDirectory": "dist",
      "runtime": "bun@1.3.12"
    }
  },
  "site": {
    "files": [
      {
        "path": "index.html",
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "size": 1024
      }
    ],
    "spa": true
  },
  "actions": [
    {
      "actionId": "actn_abcdefghijklmnopqrstuvwx",
      "revisionId": "rvsn_publishedaction"
    }
  ],
  "expectedDraft": {
    "revisionId": "rvsn_draft123",
    "sequence": 1
  }
});

Request body

json
{
  "source": {
    "files": [
      {
        "path": "src/main.tsx",
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "size": 1024
      }
    ],
    "build": {
      "command": "bun run build --base=./",
      "outputDirectory": "dist",
      "runtime": "bun@1.3.12"
    }
  },
  "site": {
    "files": [
      {
        "path": "index.html",
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "size": 1024
      }
    ],
    "spa": true
  },
  "actions": [
    {
      "actionId": "actn_abcdefghijklmnopqrstuvwx",
      "revisionId": "rvsn_publishedaction"
    }
  ],
  "expectedDraft": {
    "revisionId": "rvsn_draft123",
    "sequence": 1
  }
}

Response

json
{
  "data": {
    "id": "appl_abcdefghijklmnopqrstuvwx",
    "workspaceId": "wksp_finance123",
    "name": "Operations portal",
    "description": "Internal operations portal",
    "deployment": {
      "status": "deploying",
      "url": "https://operations-portal-abcdefghijklmnopqrstuvwx.usepermute.com",
      "revisionId": "rvsn_draft123",
      "error": null
    },
    "draft": {
      "revisionId": "rvsn_draft123",
      "sequence": 1
    },
    "createdAt": "2026-09-30T12:00:00.000Z",
    "updatedAt": "2026-09-30T12:00:00.000Z"
  }
}