autessa.customAppsV2
Custom App source files, builds, environment variables, and publishing.
autessa.customAppsV2.allREAD
autessa.customAppsV2.all()List every custom app you can access in the current company.
Returns each accessible app with its latest/published version numbers, hosting mode, slug, and your access level. Not paginated.
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
apps- Type
- CustomAppV2Dto[]
- Description
autessa.customAppsV2.buildFilesREAD
autessa.customAppsV2.buildFiles({ appId, version })List all files of a built version with presigned download URLs.
Each file carries a presigned URL valid for expiresInSeconds (about one hour). A null version serves the latest published build.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
version- Type
- number
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
version- Type
- number
- Description
- Name
baseUrl- Type
- string
- Description
- Name
files- Type
- BuildFileDto[]
- Description
- Name
expiresInSeconds- Type
- number
- Description
autessa.customAppsV2.buildStatusMUTATE
autessa.customAppsV2.buildStatus({ appId, version })Poll a version's build status (BUILDING | SUCCESS | FAILED | NOT_STARTED); polling after publish is mandatory, because the first poll that sees SUCCESS finalizes the publish (marks the version published, pins the lockfile, invalidates the CDN).
A null version means the latest. Treat NOT_STARTED right after publish as keep-polling, not an error. On SUCCESS the response carries outputUrl. On FAILED the response carries buildLogExcerpt — a bounded tail of the build's stderr (the actual vite/npm error) — so you can fix the offending file and re-publish without a separate log fetch.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
version- Type
- number
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
version- Type
- number
- Description
- Name
buildId- Type
- string
- Description
- Name
status- Type
- "BUILDING" | "SUCCESS" | "FAILED" | "NOT_STARTED"
- Description
- Name
error- Type
- string
- Description
- Name
startedAt- Type
- string
- Description
- Name
completedAt- Type
- string
- Description
- Name
outputUrl- Type
- string
- Description
- Name
buildLogExcerpt- Type
- string
- Description
autessa.customAppsV2.buildUrlREAD
autessa.customAppsV2.buildUrl({ appId })Generate a short-lived signed preview URL for the app's latest published version.
Errors until a publish has completed and been observed as SUCCESS via customAppsV2.buildStatus. The URL expires; read expiresAt (epoch seconds).
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
previewUrl- Type
- string
- Description
- Name
expiresAt- Type
- number
- Description
autessa.customAppsV2.checkSlugREAD
autessa.customAppsV2.checkSlug({ appId, publicSlug })Check whether a public URL slug is available and validly formatted, returning {available, reason}.
Pass appId so the app's own current slug counts as available. Call before customAppsV2.share with a non-default hosting mode, which requires a valid slug.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
publicSlug- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
available- Type
- boolean
- Description
- Name
reason- Type
- string
- Description
autessa.customAppsV2.cloneMUTATE
autessa.customAppsV2.clone({ appId, appName })Create a new private app you own by copying another app's draft source files.
Copies only the draft source; versions, publish state, hosting config, and custom domains are not carried over — the clone starts unpublished and private. Requires READ access to the source app.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
appName- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
- Name
files- Type
- string[]
- Description
autessa.customAppsV2.createMUTATE
autessa.customAppsV2.create({ appName, description, templateType })Create a new custom web app from a starter template and bootstrap its draft files.
Required: appName. ALWAYS pass templateType explicitly, chosen by the app's purpose for good out-of-the-box styling: LANDING_PAGE for a marketing/informational page, SAAS_APP for an interactive multi-screen product app (email client, CRM, portal), DASHBOARD for a data/analytics view; use bare BOOTSTRAP only for an intentionally empty canvas. create returns a workspaceId (a ready-to-edit workspace handle, e.g. ws-1) — write your files with customAppsV2.workspace.files.write/writeBatch using it, review with customAppsV2.workspace.status, ship with customAppsV2.workspace.publish, then poll customAppsV2.buildStatus until SUCCESS or FAILED. Call customAppsV2.workspace.checkout only if you need an additional/fresh working copy.
Request fields
- Name
appName- Type
- string
- Description
- Name
description- Type
- string
- Description
- Name
templateType- Type
- "BOOTSTRAP" | "LANDING_PAGE" | "SAAS_APP" | "DASHBOARD"
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
- Name
files- Type
- string[]
- Description
- Name
workspaceId- Type
- string
- Description
- Name
rawWorkspaceId- Type
- string
- Description
autessa.customAppsV2.deleteMUTATE
autessa.customAppsV2.delete({ appId })Permanently delete an app: its custom domains, all draft/version/build files, and database rows.
Irreversible. Requires ADMIN access. Any open server-side workspaces for the app are reaped along with it.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
autessa.customAppsV2.domains.addMUTATE
autessa.customAppsV2.domains.add({ appId, domainName })Attach a customer-owned custom domain to a PUBLIC-hosted app and get the CNAME (and possibly TXT verification) records the domain owner must create.
ADMIN only. Provisioning is asynchronous and can take minutes to days: poll domains.status (PENDING_TXT/PENDING_DNS to PROVISIONING to ACTIVE), and use domains.verify to force a recheck.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
domainName- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
domain- Type
- CustomAppDomainDto
- Description
autessa.customAppsV2.domains.removeMUTATE
autessa.customAppsV2.domains.remove({ appId, domainId })Detach a custom domain from an app and tear down its CDN tenant.
ADMIN only. The domain stops serving the app immediately.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
domainId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
autessa.customAppsV2.domains.statusREAD
autessa.customAppsV2.domains.status({ appId })List an app's custom domains with status, CNAME target, live URL when ACTIVE, and the TXT verification record when PENDING_TXT.
The place to poll while a domain provisions.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
domains- Type
- CustomAppDomainDto[]
- Description
- Name
cnameTarget- Type
- string
- Description
autessa.customAppsV2.domains.verifyMUTATE
autessa.customAppsV2.domains.verify({ appId, domainId })Synchronously run one step of domain provisioning (DNS check, tenant creation, certificate attach) instead of waiting for the next scheduled poll; also resets a FAILED domain for retry.
Call after the domain owner has created the requested DNS records to advance provisioning immediately.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
domainId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
domains- Type
- CustomAppDomainDto[]
- Description
- Name
cnameTarget- Type
- string
- Description
autessa.customAppsV2.files.createMUTATE
autessa.customAppsV2.files.create({ appId, filePath, content })Create or overwrite a single draft file at filePath with content (an unconditional upsert, identical to files.update).
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Paths under src/autessa/ are rejected (read-only). Prefer files.saveBatch when writing multiple files. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
filePath- Type
- string
- Description
- Name
content- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.files.deleteMUTATE
autessa.customAppsV2.files.delete({ appId, filePath })Delete a single draft file by filePath.
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Paths under src/autessa/ are rejected (read-only). Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
filePath- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.files.listREAD
autessa.customAppsV2.files.list({ appId })List all draft file paths of an app, plus the separate read-only platform library files under src/autessa/.
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. readOnlyFiles are readable (they are the app's SDK reference) but cannot be written.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
files- Type
- string[]
- Description
- Name
readOnlyFiles- Type
- string[]
- Description
autessa.customAppsV2.files.readREAD
autessa.customAppsV2.files.read({ appId, filePath })Read one draft file's content by its app-root-relative filePath (for example src/App.tsx).
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Reads the shared draft. For the isolated working-copy flow use customAppsV2.workspace.files.read instead.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
filePath- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
filePath- Type
- string
- Description
- Name
content- Type
- string
- Description
autessa.customAppsV2.files.readBatchREAD
autessa.customAppsV2.files.readBatch({ appId, filePaths })Read multiple draft files in one call; the response maps each found path to its content (missing paths are simply absent).
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Fewer round-trips than reading files one at a time.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
filePaths- Type
- string[]
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
files- Type
- object
- Description
autessa.customAppsV2.files.renameMUTATE
autessa.customAppsV2.files.rename({ appId, oldPath, newPath })Move or rename a draft file from oldPath to newPath.
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Both paths are rejected if under src/autessa/ (read-only). Remember to update any imports and route entries that reference the moved file. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
oldPath- Type
- string
- Description
- Name
newPath- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.files.saveBatchMUTATE
autessa.customAppsV2.files.saveBatch({ appId, files })Create or overwrite many draft files in one call via a filePath-to-content map — the preferred way to write app code.
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Paths under src/autessa/ are rejected (read-only). Do not hand-write package-lock.json — the platform pins it from the build after each successful publish. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
files- Type
- object
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
savedPaths- Type
- string[]
- Description
autessa.customAppsV2.files.updateMUTATE
autessa.customAppsV2.files.update({ appId, filePath, content })Overwrite a single draft file's content at filePath (an unconditional upsert, identical to files.create).
Direct-to-draft (no working copy). For agent-driven building prefer customAppsV2.workspace.* — see the namespace overview. Use this only for a quick read or a deliberate one-off draft write outside a workspace session. Paths under src/autessa/ are rejected (read-only). Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
filePath- Type
- string
- Description
- Name
content- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.getREAD
autessa.customAppsV2.get({ appId })Fetch one app's full details (versions, hosting mode, slug, public URL, your access level) plus its draft file listing.
Reading an app also refreshes its read-only src/autessa/** library files to the platform's current versions, so files reflects the up-to-date draft tree.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
- Name
files- Type
- string[]
- Description
autessa.customAppsV2.getSharingDetailsREAD
autessa.customAppsV2.getSharingDetails({ appId })Get an app's sharing level, company permission, hosting mode, per-user grants, and your own access level.
Read-only view of exactly what customAppsV2.share would modify.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
sharingLevel- Type
- "PRIVATE" | "SPECIFIC_MEMBER" | "COMPANY"
- Description
- Name
companyPermissionLevel- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
- Name
hostingMode- Type
- "DEFAULT" | "PUBLIC" | "AUTH_CODE" | "CUSTOM_AUTH"
- Description
- Name
sharedWith- Type
- UserShareWrapper[]
- Description
- Name
userAccessLevel- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
autessa.customAppsV2.publishMUTATE
autessa.customAppsV2.publish({ appId })Snapshot the draft into a new immutable version and start an asynchronous build; returns {version, buildId, buildStatus: BUILDING} immediately.
This publishes the current DRAFT as-is. If you built in a workspace, use customAppsV2.workspace.publish (or customAppsV2.workspace.flush first) — otherwise your workspace edits are NOT included. Publishing is finalized only by polling customAppsV2.buildStatus until SUCCESS or FAILED — the first poll that observes SUCCESS is what marks the version published and flushes CDN caches. Requires PUBLISH or ADMIN access. Errors in this response mean the build trigger failed and the version was rolled back.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
- Name
version- Type
- number
- Description
- Name
buildId- Type
- string
- Description
- Name
buildStatus- Type
- string
- Description
autessa.customAppsV2.refreshLibrariesMUTATE
autessa.customAppsV2.refreshLibraries({ appId })Force-refresh the read-only Autessa SDK library files (src/autessa/) in the app's draft to the platform's current versions.
Rarely needed explicitly — customAppsV2.get and files.list refresh them automatically.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
refreshedFiles- Type
- string[]
- Description
autessa.customAppsV2.rollbackMUTATE
autessa.customAppsV2.rollback({ appId, version })Reset the app's draft to a previously published version's source files (a restore, not a re-publish).
Copies versions/vN/source back into the draft: files the version had are written, draft files it did not have are removed (read-only src/autessa/** library files are left intact). This does NOT publish — review the restored draft, then customAppsV2.publish to make it live. version must be an existing version number (see customAppsV2.versions). Requires PUBLISH or ADMIN access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
version- Type
- number
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
- Name
version- Type
- number
- Description
- Name
files- Type
- string[]
- Description
autessa.customAppsV2.tableSecurityMUTATE
autessa.customAppsV2.tableSecurity({ appId, tablePolicies })Replace the app's runtime AutessaDB security policies (row/column security applied to the app's end-users) with the given tablePolicies.
Wholesale replace, never a merge — send the complete desired policy set; omitted tables lose their policies. Requires WRITE on the app and ADMIN on every AutessaDB table referenced.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
tablePolicies- Type
- DbRoleTablePolicyDto[]
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
role- Type
- DbRoleDto
- Description
autessa.customAppsV2.updateMUTATE
autessa.customAppsV2.update({ appId, appName, description, seoTitle, seoDescription, seoOgImageUrl })Update an app's metadata: appName, description, and public SEO fields.
Only the fields you send are changed; omitted fields are left as-is. Changing SEO fields on a PUBLIC-hosted app automatically rebuilds the published version, because SEO is baked in at build time. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
appName- Type
- string
- Description
- Name
description- Type
- string
- Description
- Name
seoTitle- Type
- string
- Description
- Name
seoDescription- Type
- string
- Description
- Name
seoOgImageUrl- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
autessa.customAppsV2.versionsREAD
autessa.customAppsV2.versions({ appId })List all versions of an app, newest first, with state, buildId, and live build status.
Use a version's number with customAppsV2.rollback to reset the draft to that version's source.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
versions- Type
- VersionDto[]
- Description
autessa.customAppsV2.vibecode.sessionREAD
autessa.customAppsV2.vibecode.session({ appId, conversationId })Fetch full details of one of your Vibecode AI-builder conversations by conversationId, including all messages and tool interactions.
Read-only. Vibecode is the visual AI app builder; this reads its conversation log.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
conversationId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
session- Type
- VibecodeSessionDto
- Description
- Name
logs- Type
- VibecodeLogDto[]
- Description
autessa.customAppsV2.vibecode.sessionsREAD
autessa.customAppsV2.vibecode.sessions({ appId, includeClosed })List your own Vibecode AI-builder conversations for an app (10 most recent; includeClosed adds closed sessions).
Read-only.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
includeClosed- Type
- boolean
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
sessions- Type
- VibecodeSessionDto[]
- Description
autessa.customAppsV2.workspace.applyChangeSetMUTATE
autessa.customAppsV2.workspace.applyChangeSet({ appId, workspaceId, writes, deletes, renames })Apply many workspace edits atomically in one call: writes (upserts), deletes, and renames, in that order, under a single lock.
The whole change set lands as one autosave, so a concurrent reader never sees it half-applied. Paths under src/autessa/ and package-lock.json are rejected (read-only). Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
writes- Type
- object
- Description
- Name
deletes- Type
- string[]
- Description
- Name
renames- Type
- object
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
appliedPaths- Type
- string[]
- Description
autessa.customAppsV2.workspace.checkoutMUTATE
autessa.customAppsV2.workspace.checkout({ appId })Check an app out into an ADDITIONAL private server-side workspace and get its workspaceId handle, editable files, and read-only files. START HERE only if you need a fresh/extra working copy — customAppsV2.create already returns an initial one.
START HERE only if you need a fresh/extra workspace — customAppsV2.create already returns an initial one. Returns a workspaceId handle (e.g. ws-2) and the file list; all subsequent edits pass this handle to workspace.files.* / workspace.applyChangeSet. Checkout copies the app's current draft into an isolated working copy that is yours alone; edit it with the autosaving workspace.files.* ops (every write/delete/rename is saved immediately into the working copy — there is no explicit save step); inspect pending changes with workspace.status; then workspace.publish to flush and publish in one step (or workspace.flush to project onto the draft with a base-hash conflict check, so concurrent draft edits are never silently clobbered), or workspace.discard to throw the working copy away leaving the draft untouched. Workspaces live only on the server, never affect the browser editor mid-edit, and are reaped automatically after ~24h idle. Requires WRITE access. Pass the returned workspaceId handle to every subsequent workspace call.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
workspaceId- Type
- string
- Description
- Name
rawWorkspaceId- Type
- string
- Description
- Name
files- Type
- string[]
- Description
- Name
readOnlyFiles- Type
- string[]
- Description
autessa.customAppsV2.workspace.discardMUTATE
autessa.customAppsV2.workspace.discard({ appId, workspaceId })Throw a workspace away: delete its working copy, leaving the app's draft untouched.
Use when abandoning an experiment. The draft is never modified by discard. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
autessa.customAppsV2.workspace.files.deleteMUTATE
autessa.customAppsV2.workspace.files.delete({ appId, workspaceId, filePath })Delete one file from the working copy by filePath — autosaved immediately.
Paths under src/autessa/ and package-lock.json are rejected (read-only). The deletion reaches the draft only when you flush. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
filePath- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.workspace.files.listREAD
autessa.customAppsV2.workspace.files.list({ appId, workspaceId })List the working copy's editable file paths plus the read-only src/autessa/ library files.
Reads within the workspace, not the shared draft.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
files- Type
- string[]
- Description
- Name
readOnlyFiles- Type
- string[]
- Description
autessa.customAppsV2.workspace.files.readREAD
autessa.customAppsV2.workspace.files.read({ appId, workspaceId, filePath })Read one file's content from the working copy by its app-root-relative filePath.
Reads within the workspace, so it reflects your autosaved edits, not the shared draft.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
filePath- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
filePath- Type
- string
- Description
- Name
content- Type
- string
- Description
autessa.customAppsV2.workspace.files.readBatchREAD
autessa.customAppsV2.workspace.files.readBatch({ appId, workspaceId, filePaths })Read multiple working-copy files in one call; the response maps each found path to its content (missing paths are simply absent).
Reads within the workspace. Fewer round-trips than reading one at a time.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
filePaths- Type
- string[]
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
files- Type
- object
- Description
autessa.customAppsV2.workspace.files.renameMUTATE
autessa.customAppsV2.workspace.files.rename({ appId, workspaceId, oldPath, newPath })Move or rename one file within the working copy from oldPath to newPath — autosaved immediately.
Both paths are rejected if under src/autessa/ or equal to package-lock.json (read-only). Update any imports and route entries referencing the moved file. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
oldPath- Type
- string
- Description
- Name
newPath- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.workspace.files.writeMUTATE
autessa.customAppsV2.workspace.files.write({ appId, workspaceId, filePath, content })Create or overwrite one file in the working copy — autosaved immediately (no separate save step).
Paths under src/autessa/ and package-lock.json are rejected (read-only). The change lands only in the working copy until you flush. Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
filePath- Type
- string
- Description
- Name
content- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
filePath- Type
- string
- Description
autessa.customAppsV2.workspace.files.writeBatchMUTATE
autessa.customAppsV2.workspace.files.writeBatch({ appId, workspaceId, files })Create or overwrite many working-copy files in one call via a filePath-to-content map — autosaved immediately.
The preferred way to write several files at once into the workspace. Paths under src/autessa/ and package-lock.json are rejected (read-only). Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
files- Type
- object
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
savedPaths- Type
- string[]
- Description
autessa.customAppsV2.workspace.flushMUTATE
autessa.customAppsV2.workspace.flush({ appId, workspaceId, onConflict })Project the workspace's changes onto the app's shared draft (writes + deletes + renames) and sync the draft, then tear the workspace down.
With the default onConflict=FAIL, the flush is refused and returns conflicts[] when the draft has drifted on a path the workspace also changed — re-checkout or reconcile, do not clobber. Pass onConflict=OVERWRITE_DRAFT to force the workspace's versions over the drifted draft. On success the workspace is consumed (its working copy is deleted). Requires WRITE access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
onConflict- Type
- "FAIL" | "OVERWRITE_DRAFT"
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
flushed- Type
- boolean
- Description
- Name
flushedPaths- Type
- string[]
- Description
- Name
conflicts- Type
- string[]
- Description
autessa.customAppsV2.workspace.listForAppREAD
autessa.customAppsV2.workspace.listForApp({ appId })List the app's currently open server-side workspaces — who opened each, when, its last activity, and how many pending changes it has relative to checkout.
Only OPEN workspaces are returned (the ones with a live working copy); flushed, discarded, and expired workspaces are omitted. This is a read: it never bumps a workspace's idle TTL, so listing does not keep a workspace alive. dirtyFileCount counts added + modified + deleted + renamed paths versus checkout, or is null when that count could not be computed. Requires READ access.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
workspaces- Type
- WorkspaceSummary[]
- Description
autessa.customAppsV2.workspace.publishMUTATE
autessa.customAppsV2.workspace.publish({ appId, workspaceId, onConflict })Flush the workspace onto the draft, then publish — a new version starts building; returns {version, buildId, buildStatus: BUILDING}. Poll customAppsV2.buildStatus for the outcome.
The normal way an agent ships work built in a workspace: flush + customAppsV2.publish in one call. Honors the same onConflict semantics as workspace.flush: with FAIL (default) a drifted draft aborts before publishing. Requires PUBLISH access. After it returns, poll customAppsV2.buildStatus (the FAILED response carries buildLogExcerpt) until SUCCESS or FAILED.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
- Name
onConflict- Type
- "FAIL" | "OVERWRITE_DRAFT"
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
app- Type
- CustomAppV2Dto
- Description
- Name
version- Type
- number
- Description
- Name
buildId- Type
- string
- Description
- Name
buildStatus- Type
- string
- Description
autessa.customAppsV2.workspace.statusREAD
autessa.customAppsV2.workspace.status({ appId, workspaceId })Show what the workspace has changed relative to checkout (added/modified/deleted/renamed), whether the draft has drifted underneath it, and whether it is clean.
draftDrifted is true when someone edited the shared draft since checkout; a subsequent workspace.flush with the default onConflict=FAIL will refuse if the drift collides with the workspace's own changes. clean is true when the workspace has no pending changes.
Request fields
- Name
appId- Type
- string (opaque id)
- Description
- References custom app v2 by opaque id.
- Name
workspaceId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
added- Type
- string[]
- Description
- Name
modified- Type
- string[]
- Description
- Name
deleted- Type
- string[]
- Description
- Name
renamed- Type
- string[]
- Description
- Name
draftDrifted- Type
- boolean
- Description
- Name
clean- Type
- boolean
- Description