Apps API

Install the apps Serenities ships, and build, save and release your own app from its files.

19 endpoints

Endpoints

POST

/api/v1/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 Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/workspaceApp/getInstall

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

Parameters

installId stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/getInstall \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "installId": "example"
}'

POST

/api/v1/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 Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/usage \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/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.

Parameters

key

stringrequired

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

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/install \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "example"
}'

POST

/api/v1/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.

Parameters

key

stringrequired

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

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/uninstall \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "example"
}'

POST

/api/v1/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.

Parameters

installId

stringrequired

The install id (from workspaceApp_list)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/pause \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "installId": "example"
}'

POST

/api/v1/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.

Parameters

installId

stringrequired

The install id (from workspaceApp_list)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/resume \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "installId": "example"
}'

POST

/api/v1/workspaceApp/createRelease

Save app: a Preview release of this workspace's own app (params: projectId, manifest = its SDK 2 app.json, notes). Builds from the app's FILES (their current version): the app needs its files first (app.json for SDK 2 with its version x.y.z, its pages and its functions, written with workspaceApp_filesWrite); an app with no files is refused and a pages-only app has to get its files first; nothing runs a Preview. Refused naming the key when app.json is wrong or removes what Live has.

Parameters

`projectId`	stringrequired
`manifest`	object	Not needed: the app's own app.json (in its files) is what is saved
`notes`	array

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/createRelease \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "manifest": {},
  "notes": {}
}'

POST

/api/v1/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.

Parameters

`projectId`	stringrequired
`version`	stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/promoteRelease \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "version": "example"
}'

POST

/api/v1/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.

Parameters

`projectId`	stringrequired
`version`	stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/rollbackRelease \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "version": "example"
}'

POST

/api/v1/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).

Parameters

projectId stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/listReleases \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example"
}'

POST

/api/v1/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.

Parameters

projectId stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesList \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example"
}'

POST

/api/v1/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.

Parameters

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

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesRead \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "path": "example"
}'

POST

/api/v1/workspaceApp/filesWrite

Save one source file of this workspace's own app, whole (params: projectId, path, content, expectedHeadHash = headHash from workspaceApp_filesList; left out for the first file of 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).

Parameters

`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`	string	headHash from workspaceApp_filesList; leave it out for the first file of an app with no files

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesWrite \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "path": "example",
  "content": "example"
}'

POST

/api/v1/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).

Parameters

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

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesDelete \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "path": "example",
  "expectedHeadHash": "example"
}'

POST

/api/v1/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.

Parameters

projectId stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesHistory \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example"
}'

POST

/api/v1/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.

Parameters

`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 Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesEdit \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "path": "example",
  "find": "example"
}'

POST

/api/v1/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.

Parameters

`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 Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesRename \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "from": "example",
  "to": "example"
}'

POST

/api/v1/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.

Parameters

`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 Request

curl -X POST https://app.serenitiesai.com/api/v1/workspaceApp/filesRestore \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "headHash": "example",
  "expectedHeadHash": "example"
}'