Back to API Overview

App actions API

Who may run an installed app’s actions, and whether each runs on its own or asks first.

5 endpoints

Endpoints

POST
/api/v1/appActions/describe

What can this installed app do? Lists one installed app's actions and the inputs each takes, so you can run one with actions_run. Params: target ("app:<installId>", the install id from workspaceApp_list). Returns { targetName, actions: [{ action, title, description, kind, inputs: [{ name, type, required, description }] }] }. An app you cannot open answers as not found.

Parameters

targetstringrequired

Example Request

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

Choose which of the person's agents may run one action of an installed app (replaces the list; a site's action is chosen on its function instead). Params: target ("app:<installId>"), action (its name), agentIds (the agents' ids; [] for none). Taking agents off applies at once, unless the save would also set the action's mode for agents (its mode was never set and an agent the person cannot see stays picked): that waits like adding one. Adding an agent may wait for the person's OK: nothing changes until they allow it on the card. A picked agent runs the action only when it is also allowed for agents with appActions_setConsent (subject all_automations, door "agent"). Call it only when the person asks, and repeat back the action and the agents. Returns { ok } (with a notice when it applied at once), or { applied: false, pendingChange } while it waits.

Parameters

targetstringrequired
actionstringrequired
agentIdsarrayrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/appActions/setAgents \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "example",
  "action": "example",
  "agentIds": {}
}'
POST
/api/v1/appActions/setConsent

Choose who may run one action of an installed app (an SDK 2 app's action, by its name in the app): agents and automations, one person, or the Developers. Params: target ("app:<installId>", the install id from workspaceApp_list), action (the action's name, e.g. "send_invoice"), subject ({ kind: "person", id: <member id> } for one active Developer or Viewer, the id from workspace_membersForAi; { kind: "role", id: "editor" } for the Developers; { kind: "all_automations", id: "*" } for agents and automations; a person or the Developers are the same person on the dashboard, in the chat and through their AI, so they take no door), door (null; or, only with all_automations, "agent" or "automation" to set agents or automations alone), value ("allowed", "not_allowed", or null to go back to the default). Default with no setting: a person runs it as their role and the action's mode allow; an agent or an automation may NOT run it until it is allowed for all automations. "allowed" never gives a person more than their role. The Owner and Admins always may and are never a subject. A change that only narrows (someone no longer allowed, or back to the default after "allowed" for agents or automations) applies at once. A change that lets someone run it who could not before (agents or automations "allowed", or a person or the Developers no longer "not_allowed") may wait for the person's OK: nothing changes until they allow it on the card. Only the Owner or an Admin may call it; call it only when asked, and repeat back the action and who it is for. To let only some of the person's own agents run it, allow it here for agents (subject all_automations, door "agent") and pick those agents with appActions_setAgents. Returns { ok } (with a notice when it applied at once), or { applied: false, pendingChange } while it waits.

Parameters

targetstringrequired
actionstringrequired
doorstringnullrequired

Allowed values: agent, automation, null

subjectobjectrequired
valuestringnullrequired

Allowed values: allowed, not_allowed, null

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/appActions/setConsent \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "example",
  "action": "example",
  "door": {}
}'
POST
/api/v1/appActions/setupAgents

Set up an installed app's agents in one step, from the app's own app.json: each agent the app comes with is picked on the actions it uses, those actions are allowed for agents (an action whose mode nobody set asks first; a mode already set stays), and the outside websites the app declares are allowed. Params: installId (from workspaceApp_list), only (optional: limit it to some of the app's items, each "agent:<agent name>", "action:<action name>" or "host:<host>" as in its app.json; anything the app does not declare is refused). It may wait for the person's OK: nothing changes until they allow it on the card. Anything the person switched off before (an action not allowed, a website refused) stays off, on the card and by hand; they turn it back on in the app's settings. Call it only when the person asks to set the app up, and repeat back what it will do. Returns { ok, notice } (notice says "Nothing to set up" when it is all set up already), or { applied: false, pendingChange } while it waits.

Parameters

installIdstringrequired
onlyarray

Example Request

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

Set how one action of an installed app or a site runs, for the person's own AI and for their agents and automations (functions and flows): "auto" (on its own), "ask" (asks the person first), "off", or "default" (back to the default by its kind: a read runs on its own, anything else asks first; an installed app's action is off for agents until the person turns it on). Params: target ("app:<installId>" or "site:<projectId>", from actions_list), action (its name), mode. A change that only narrows (less on its own, or off) applies at once. A change that lets the AI, agents or automations do more (to "auto", or from "off" to "ask") may wait for the person's OK: nothing changes until they allow it on the card. Call it only when the person asks, and repeat back the action and the mode. Returns { ok } (with a notice when it applied at once), or { applied: false, pendingChange } while it waits.

Parameters

targetstringrequired
actionstringrequired
modestringrequired

Allowed values: auto, ask, off, default

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/appActions/setMode \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "example",
  "action": "example",
  "mode": "example"
}'