Official Apps Tools

Tools for installing, updating, and removing the apps Serenities ships.

19 tools

Available Tools

workspaceApp_list

The apps Serenities ships, with this account's install state (for example Social: a calendar and composer for the account's social channels). For each: installed or not, the install id to open it at /dashboard/apps/i/<installId>/open, the version it runs, whether a newer release exists, and legacyProjectId when an older copy install has not yet moved onto a release.

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_list",
    "arguments": {}
  }
}

workspaceApp_getInstall

One install of this account's (params: installId): its app, name, version and whether it is ready to open.

Input Schema

installId stringrequired

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_getInstall",
    "arguments": {
          "installId": "example"
    }
  }
}

workspaceApp_usage

How many workspace apps this workspace has and how many its plan allows: { used, limit } (limit is null when the plan has no limit; 0 means the plan includes no workspace apps). Apps built here and apps installed from the app store count together. Check it before creating or enabling an app.

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_usage",
    "arguments": {}
  }
}

workspaceApp_install

Enable an official app for this account (params: key, e.g. "social"). One release of the app is built once and shared by everyone who has it; enabling creates a row and a base of the account's own — no copy, no build. Re-running moves an existing install to the newest release and is never refused. A NEW install is a workspace app and counts against the plan's limit on workspace apps: when the workspace is full, or its plan includes none, the call is refused with a plain message and an upgrade link — tell the person that message and give them the link, never retry.

Input Schema

key

stringrequired

App key from list, e.g. "social"

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_install",
    "arguments": {
          "key": "example"
    }
  }
}

workspaceApp_uninstall

Remove an official app from this account (params: key). Deletes the install row; the account's base, social channels and posts are kept, and nothing of the vendor's is touched. Act only on what the person named or picked.

Input Schema

key

stringrequired

App key from list, e.g. "social"

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_uninstall",
    "arguments": {
          "key": "example"
    }
  }
}

workspaceApp_pause

Pause one installed app (params: installId): a safety stop. While paused, people can still open it and read, but nothing it does can change anything (writes, sends, its automations and agents are refused, and say it is paused). Undo with workspaceApp_resume. Pausing an app that is already paused changes nothing. Refused while the server has not switched pausing on.

Input Schema

installId

stringrequired

The install id (from workspaceApp_list)

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_pause",
    "arguments": {
          "installId": "example"
    }
  }
}

workspaceApp_resume

Resume an app a person paused (params: installId). The person who paused it may; when you may not, the refusal says whom to ask. An app paused by the platform (over the plan's app count, or its daily limit) cannot be resumed here: it starts again by itself when the cause clears, and the refusal says what to do. Resuming a running app changes nothing. Only a person resumes an app: flows, functions and agents are refused.

Input Schema

installId

stringrequired

The install id (from workspaceApp_list)

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_resume",
    "arguments": {
          "installId": "example"
    }
  }
}

workspaceApp_createRelease

Save app: a Preview release of this workspace's own app (params: projectId, manifest = its SDK 2 app.json, notes). Builds its current pages once; nothing runs a Preview. Refused naming the key when app.json is wrong or removes what Live has.

Input Schema

`projectId`	stringrequired
`manifest`	objectrequired	app.json (SDK 2)
`notes`	array

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_createRelease",
    "arguments": {
          "projectId": "example",
          "manifest": {},
          "notes": {}
    }
  }
}

workspaceApp_promoteRelease

Make a saved Preview of this workspace's own app Live for the whole workspace (params: projectId, version). Refused naming the field when it removes what Live has now.

Input Schema

`projectId`	stringrequired
`version`	stringrequired

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_promoteRelease",
    "arguments": {
          "projectId": "example",
          "version": "example"
    }
  }
}

workspaceApp_rollbackRelease

Move this workspace's own app back to an earlier version that was Live (params: projectId, version); later versions are no longer offered.

Input Schema

`projectId`	stringrequired
`version`	stringrequired

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_rollbackRelease",
    "arguments": {
          "projectId": "example",
          "version": "example"
    }
  }
}

workspaceApp_listReleases

The versions of this workspace's own app (params: projectId): version and stage (live, earlier, preview; Previews only when you may create apps).

Input Schema

projectId stringrequired

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_listReleases",
    "arguments": {
          "projectId": "example"
    }
  }
}

workspaceApp_filesList

The source files of this workspace's own app (params: projectId): headHash (the current version; null when it has no files yet), updatedAt, and each file's path, size and hash. Pass headHash as expectedHeadHash to workspaceApp_filesWrite / filesEdit / filesRename / filesDelete / filesRestore.

Input Schema

projectId stringrequired

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesList",
    "arguments": {
          "projectId": "example"
    }
  }
}

workspaceApp_filesRead

Read one source file of this workspace's own app (params: projectId, path from workspaceApp_filesList): a text file answers its whole content; an image or font answers its size and type, never its bytes.

Input Schema

`projectId`	stringrequired
`path`	stringrequired	A file path from workspaceApp_filesList, e.g. "pages/Home.tsx"

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesRead",
    "arguments": {
          "projectId": "example",
          "path": "example"
    }
  }
}

workspaceApp_filesWrite

Save one source file of this workspace's own app, whole (params: projectId, path, content, expectedHeadHash = headHash from workspaceApp_filesList, null only for an app with no files). Makes a new version (earlier ones are listed by workspaceApp_filesHistory); nothing goes live until a release. Refused when someone saved first (list again, redo the change), when it breaks a file rule (path, 1 MB per file, 500 files, 25 MB) or holds a secret (declare it in app.json instead).

Input Schema

`projectId`	stringrequired
`path`	stringrequired	e.g. "pages/Home.tsx": app.json, or a file in pages, components, functions, assets or api
`content`	stringrequired	The whole file, as text (UTF-8)
`expectedHeadHash`	stringrequired	headHash from workspaceApp_filesList (null only when the app has no files yet)

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesWrite",
    "arguments": {
          "projectId": "example",
          "path": "example",
          "content": "example"
    }
  }
}

workspaceApp_filesDelete

Remove one source file of this workspace's own app (params: projectId, path, expectedHeadHash = headHash from workspaceApp_filesList). Makes a new version (earlier ones are listed by workspaceApp_filesHistory); the last file cannot be removed. Undo it with workspaceApp_filesRestore (headHash = the version before the delete, first in workspaceApp_filesHistory).

Input Schema

`projectId`	stringrequired
`path`	stringrequired
`expectedHeadHash`	stringrequired	headHash from workspaceApp_filesList

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesDelete",
    "arguments": {
          "projectId": "example",
          "path": "example",
          "expectedHeadHash": "example"
    }
  }
}

workspaceApp_filesHistory

The earlier versions of this workspace's own app's files, newest first, at most 100 (params: projectId): headHash, when it was replaced, and who had saved it (a person's name and role, or an automation's name and kind). Pass a headHash to workspaceApp_filesRestore to make that version current again.

Input Schema

projectId stringrequired

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesHistory",
    "arguments": {
          "projectId": "example"
    }
  }
}

workspaceApp_filesEdit

Change one passage of one text file of this workspace's own app (params: projectId, path, find, replace, expectedHeadHash = headHash from workspaceApp_filesList): `find` must occur exactly once in the file (copy it exactly, with enough around it to match one place; 0 or several matches are refused, saying how many) and becomes `replace`. Makes a new version, held to the same rules as workspaceApp_filesWrite (1 MB per file, 25 MB, no secret); nothing goes live until a release.

Input Schema

`projectId`	stringrequired
`path`	stringrequired	A text file path from workspaceApp_filesList, e.g. "pages/Home.tsx"
`find`	stringrequired	The exact text to change; it must occur exactly once in the file
`replace`	stringrequired	The text to put in its place (empty removes it)
`expectedHeadHash`	stringrequired	headHash from workspaceApp_filesList

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesEdit",
    "arguments": {
          "projectId": "example",
          "path": "example",
          "find": "example"
    }
  }
}

workspaceApp_filesRename

Rename or move one source file of this workspace's own app (params: projectId, from, to, expectedHeadHash = headHash from workspaceApp_filesList). The file keeps its content; `to` must follow the file path rules and must not exist yet. Makes a new version, undone with workspaceApp_filesRestore.

Input Schema

`projectId`	stringrequired
`from`	stringrequired	The file's path now, from workspaceApp_filesList
`to`	stringrequired	Its new path (the same file rules as a write)
`expectedHeadHash`	stringrequired	headHash from workspaceApp_filesList

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesRename",
    "arguments": {
          "projectId": "example",
          "from": "example",
          "to": "example"
    }
  }
}

workspaceApp_filesRestore

Make an earlier version of this workspace's own app's files current again (params: projectId, headHash = an earlier version from workspaceApp_filesHistory, expectedHeadHash = headHash from workspaceApp_filesList). It is a new version: the one it replaces goes to workspaceApp_filesHistory, so a restore is undone the same way. Refused when a file of that version is no longer stored.

Input Schema

`projectId`	stringrequired
`headHash`	stringrequired	The earlier version to make current: a headHash from workspaceApp_filesHistory
`expectedHeadHash`	stringrequired	headHash from workspaceApp_filesList (the version now)

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "workspaceApp_filesRestore",
    "arguments": {
          "projectId": "example",
          "headHash": "example",
          "expectedHeadHash": "example"
    }
  }
}