Back to API Overview

Functions API

Every function, on your sites and in your workspace: create, change, run, versions and runs.

18 endpoints

Endpoints

POST
/api/v1/functions/list

List the workspace's functions in one list, one page at a time, ordered by name: the workspace's own and every site's (only the sites you may open). Answers { items, nextCursor }: when nextCursor is not null there are more, so call again with cursor = that nextCursor (null = the last page). Params, all optional: limit (1 to 100, 50 when left out; more is refused), cursor, trigger (only the functions with that trigger: "schedule", "webhook", "email" (an inbound email address), "event" (an account event), "tableEvent" (a site's table, sign-up or sign-in event) or "page" (a site's page can call it)), enabled (with trigger: true = that trigger is on, false = it is off), where ("workspace" = only those that live in the workspace, "site" = only those that live in a site), projectId (only that site's; never with where "workspace"). "Schedules" are this list with trigger "schedule": there is no other schedules list. Each item: id, name, description, summary, kind ("code" | "data"), projectId (null = it lives in the workspace, else its site), isActive, exposed, updatedAt, where ({ kind: "workspace" } or { kind: "site", siteId, siteName }) and triggers ([{ kind, enabled }]: what starts it and whether that is on; a kind only, never a token, address or schedule time). Read one with functions_get; its triggers with functions_listTriggers.

Parameters

limitinteger

How many functions on this page: 1 to 100 (50 when left out).

cursorstring

The nextCursor of the page before, for the next page. Leave it out for the first page.

triggerstring

Only the functions with this trigger: "schedule", "webhook", "email" (an inbound email address), "event" (an account event), "tableEvent" (a site's table, sign-up or sign-in event) or "page" (a site's page can call it).

Allowed values: schedule, webhook, email, event, tableEvent, page

enabledboolean

With trigger: true = only those whose trigger of that kind is on, false = only those whose trigger of that kind is off. Left out: both.

wherestring

"workspace" = only the functions that live in the workspace; "site" = only the functions that live in a site.

Allowed values: workspace, site

projectIdstring

Only this site's functions (from site_listProjects). Leave it out for every function: the workspace's and every site's.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": {},
  "cursor": "example",
  "trigger": "example"
}'
POST
/api/v1/functions/listTriggers

Every trigger of ONE function or of ONE site, one page at a time: what starts it and whether that is on. Send exactly one of id (one function's triggers, a function in the workspace or in a site, from functions_list) or projectId (every trigger of every function that lives in that site, plus the schedules kept in that site aimed at a function in the workspace; from site_listProjects): both or neither is refused. Optional: kind (only that kind: "schedule", "webhook", "email", "event", "tableEvent" or "page"; projectId with kind "schedule" is the site's Schedules list), limit (1 to 50, 50 when left out; more is refused), cursor (the nextCursor of the page before). Answers { items, nextCursor } (nextCursor null = the last page), ordered by function name, then function id, then kind (schedule, webhook, email, event, tableEvent, page), then the trigger's id. Each item: functionId, functionName, kind, store (where the trigger is kept, so which tools change it: "workspace" = automations_setScheduleActive / automations_deleteSchedule for a schedule, automations_setWebhookActive / automations_deleteWebhook for a webhook, automations_updateMailhook / automations_deleteMailhook for an email address, accountEvents_updateEventTrigger / accountEvents_removeEventTrigger for an event; "site" = site_updateSchedule / site_deleteSchedule for a schedule, the site's automations for a table event), id (the trigger's own id; for kind "page" the function's id), enabled (on or off), summary (plain words: a schedule's time and timezone, an event, a table event and its table) and lastRunAt (when it last started the function, or null; a table event and a page have none; for a webhook it is updated at most once a minute, so a call a few seconds ago may not show yet); a schedule also carries nextRunAt (its next start; null when the schedule is switched off), cron (its expression) and blocked (the Free-plan note when it is on but will not fire, else null), and these three are null on any other kind. It never shows a webhook's token or URL, an email address, a schedule's params, an event's filters or config, or code.

Parameters

idstring

One function's triggers: its id (from functions_list), a function in the workspace or in a site. Send this or projectId, never both.

projectIdstring

Every trigger of every function that lives in this site (from site_listProjects), and the schedules kept in this site aimed at a function in the workspace. Send this or id, never both.

kindstring

Only this kind of trigger: "schedule", "webhook", "email" (an inbound email address), "event" (an account event), "tableEvent" (a site's table, sign-up or sign-in event) or "page" (a site's page can call it).

Allowed values: schedule, webhook, email, event, tableEvent, page

limitinteger

How many triggers on this page: 1 to 50 (50 when left out).

cursorstring

The nextCursor of the page before, for the next page. Leave it out for the first page.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/listTriggers \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "projectId": "example",
  "kind": "example"
}'
POST
/api/v1/functions/get

Get one function, wherever it lives. Params: id (on its own it opens any function), or name (on its own the function of that name in the workspace; with projectId that site's). Returns its code (a data function: its definition), kind, projectId, grants, summary, accessRules, isActive, its `updatedAt` (send it as seenUpdatedAt on functions_update) and its `version` (send it as seenVersion when you prepare "Runs as Admin" with functions_setCapabilities or the switch with functions_setIdentityMode); a site's function also answers accessRuleUses: the places in its site whose access rule names it (switching it off makes those rules let no one in).

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/get \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/create

Create a function, in the workspace (no projectId) or in a site (projectId), a code function (kind "code", the default) or a site's data function (kind "data", no code). PAID PLANS ONLY for a site's function (refused on Free). Returns { id, name, isActive, updatedAt, projectId, kind, draftVersionId }: draftVersionId is the draft this saved (the one to test or publish). When its accessRules let in "Anyone on the internet" it answers pendingChange instead: a card a person taps, and nothing is made until then (say so). CODE: `code` runs as a function BODY with `ctx` and `params` in scope (`export default async (params, ctx) => {…}` is also accepted; `import` is not). A function in the workspace reaches a site's tables through ctx.sites['<Site Name>'] (grants.bases), a standalone Base through ctx.connections.call('Serenities', tool, args) with the Base's id on grants.databaseIds, and its connections on its grants (Each site in grants.bases can be given as Read or Read and write: { projectId, access: "read" } = Read (the function can look at the site's tables and files but every write is refused: "This function may only read <site>"), { projectId, access: "write" } = Read and write; no access saved counts as Read and write. On the function's Access tab (Site access) a person picks it per site; a newly ticked site starts as Read, so give a site as Read unless the function must change it. SERENITIES TOOLS: grants.serenitiesTools: ["tables_getRows", …], empty by default, only tools the person you act for may use; never functions_invoke (use ctx.functions.run) or a person-only tool). A code function that lives in a site reaches THIS site's tables (its one linked base) through ctx.tables (getRows, getRow, createRow, updateRow, deleteRow, searchRows, filterRows, getRowCount, readAll, report, listTables, getTableSchema, upsertRow, bulkUpdateRows, bulkDeleteRows), files (ctx.files), ctx.email (send, sendVia, accounts — sends from the owner's own mailbox), external HTTP (ctx.fetch; a secret on its list is used through ctx.secrets.ref("NAME"), filled in only for its listed hosts), ctx.secrets.verifyHmac, ctx.env.get / ctx.env.set (plain, non-secret APP_* settings; ctx.env.set of one that a function taking payments for sites lists in its secrets is refused, except from that function itself when no other such function lists it; a payment function lists the APP_ settings it relies on, an unlisted one is not protected), ctx.connections (only the apps ticked under Authorised connections), ctx.events.emit, ctx.realtime.publish and ctx.user; a page calls it with functions.invoke("name", params). WRITES ARE STRICT: every key passed to createRow/updateRow/upsertRow/bulkUpdateRows must be an existing field of that table, spelled exactly (case-sensitive); call getTableSchema first and createField for a new one. A secret field can't be the match field of upsertRow (it answers 400 and writes nothing): match on another field, or update by row id. ctx.tables.bulkUpdateRows answers { results, updated, failed }: check `failed` (and the per-row `results`) before reporting success: some rows can fail while others save; a select field takes the option's VALUE, not its label. A run's platform calls are limited: use the bulk calls, not loops. Deny by default: a function with no access rule is refused for site users on every route, a page-started run reads only what that person may read ("Runs as Admin", and any change to a function that has it, waits for a person to allow its card), and a function that lives in a site uses only its site's own base. Read getCodeGuide topic "functions" for the full rules. DATA: kind "data" + projectId + definition ({ operation, tableName, params:[{name,type}], data/filter templates with {"$param":"name"} placeholder nodes }) + accessRules ({ execute: [...] }, required or nobody can call it); leave runAs out (it runs with the caller's own row permissions). A data function gets "Runs as Admin" the same way, and it waits for a person: make the function with functions_create (kind "data"; it runs with the caller's own permissions), then functions_setIdentityMode with mode "workspace" and the seenVersion from functions_get answers with pendingChange, a card that switches it on when a person taps Allow. runAs "service" is refused (nothing changes). Tell the person it waits for their tap. Prefer it over code for plain create/read/update/delete. Params: name (1 to 100 characters, no ":" or "%", unique where it lives, any capitals), projectId?, kind?, description?, code?, definition?, grants? (a function in the workspace; one made in a site gets its connections with functions_update), accessRules? ({ execute, runBy }: who may call it; no rule = nobody but the owner's side; runBy = "Who can run this function"), runAs? (data), timeout? (a code function's limit, ms), maxRetries? (0 = run once, the default; more only for work that is safe to run twice), toolSpec? ({ inputSchema, outputSchema?, returns?, sideEffects?, kind? }, written with the code), exposed?. A field that does not apply to that kind of function is refused. A new function in the workspace starts switched off (isActive false): switch it on with functions_update before pointing a webhook, schedule or mailhook at it. POWERS (email, env, a site's users / entitlements) are refused until a person allows them: prepare them with functions_setCapabilities and the person allows the card; "Runs as Admin" (functions_setIdentityMode) is a card too. An AI agent needs "Can create functions" switched on by a person; its function's grants are copied from the agent. WHO RUNS IT: a function runs as the workspace; whoever builds it decides what it can do and can only wire what they may use (the save is refused otherwise); who started it is passed in as data (ctx.run.startedBy), never as rights; a site visitor's call sees only what that visitor may see. No "Ask first" inside a function: each call is allowed or refused. Check runner-supplied inputs (row, address, amount) before acting. A save is a draft: a person's own call (Test, functions_invoke, their own AI chat or AI client over MCP, their API key) runs it; every other start (schedule, webhook, event, flow, agent, page) runs the published version only: a schedule needs functions_publish first.

Parameters

namestringrequired

Its name: 1 to 100 characters, no ':' or '%', unique where it lives (the workspace, or its site) whatever the capital letters. A site's page calls a function that lives in that site with functions.invoke("name", params).

projectIdstring

The site to make it in (from site_listProjects). Leave it out for a function in the workspace.

kindstring

"code" (the default): JavaScript in the sandbox. "data": a declarative data operation of a site, no code (send definition and projectId).

Allowed values: code, data

descriptionstring

What it does.

codestring

A code function's body, run with `params` and `ctx` in scope (`export default async (params, ctx) => {…}` is also accepted; `import` is not).

definitionobject

A data function's definition: { operation, tableName, params, data / filter templates with {"$param":"name"} nodes, … }.

grantsobject

What it may use: the sites, Bases, tables, connections and Serenities tools (a function in the workspace). A function made in a site takes none here: set its connections with functions_update once it exists.

accessRulesobject

Who may call it: { execute, runBy }. No rule = nobody but the owner's side.

runAsstring

A data function only: "member" (the default) = the caller's own row permissions.

Allowed values: member, service

timeoutinteger

A code function's time limit in ms (1000 to 840000, default 30000), wherever it lives. A function may run up to 14 minutes (30 seconds when none is set). Runs started by a schedule, a flow, an agent or the queue (and account events and mailhooks) can use all 14 minutes, flows and agents within their own time limits; a call that waits for its answer, like a site page's call, cannot: a site's own address cuts a silent call after about 100 seconds.

maxRetriesinteger

Retries when an automation runs it and it fails. 0 = run once (the default); more only for work that is safe to run twice.

toolSpecobject

Its MCP-tool schema, written with the code: { inputSchema, outputSchema?, returns?, sideEffects?, kind? }.

exposedboolean

true = automations and AI may call it as a method (a function that lives in a site: a method of its site).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/create \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "projectId": "example",
  "kind": "example"
}'
POST
/api/v1/functions/update

Change a function, wherever it lives (code or data). Name it by id (alone), or by name (+ projectId for a site's). Send only what changes: newName (as in functions_create), description, summary (its one-line summary, any code function: at most 500 characters; a longer one is refused), code, definition (a data function), isActive, timeout, maxRetries (0 = run once; more only for work that is safe to run twice), grants (A function's grants are replaced WHOLE when you send them: read them first (functions_get), add the site to grants.bases (one entry per site it touches, { projectId }), and send the rest unchanged — its connected apps (grants.connections) and Serenities tools (grants.serenitiesTools) included, or they are removed. Each site in grants.bases can be given as Read or Read and write: { projectId, access: "read" } = Read (the function can look at the site's tables and files but every write is refused: "This function may only read <site>"), { projectId, access: "write" } = Read and write; no access saved counts as Read and write. On the function's Access tab (Site access) a person picks it per site; a newly ticked site starts as Read, so give a site as Read unless the function must change it. A function that lives in a site holds only connections here: it reads its own site's base through ctx.tables), connections (any code function: its "Authorised connections" [{ id, tools? }], the list grants.connections also holds; replaces that list and keeps the rest of its grants, [] = none; never together with grants; set by a person or their own AI, never an agent or a flow), accessRules ({ execute, runBy }: who may call it), runAs (a data function), toolSpec (changed together with the code; null removes it), adapterSpec (any code function: its payment provider spec, a PaymentAdapterSpec whose key is 1 to 64 of a-z, 0-9, '-' and '_' and never a built-in's such as pesapal, stripe or manual, of at most 32 KB with credential field names, never a value; saved as a draft like the code; how it is offered to sites and switched on is in this parameter's own text; null removes it; on a function already live as a provider, a change from the AI waits for a person's tap), exposed, seenUpdatedAt (the `updatedAt` functions_get or your last save answered: refused if it was saved since; leave it out if unread), seenVersion (the version shown, where a change asks for it). A field that does not apply to that kind of function is refused, and a call that sends nothing to change is refused ("Nothing to change"); the answer carries the new `updatedAt` and `draftVersionId` (the draft to test or publish with functions_publish; none where the function keeps no draft). PUBLISHED-APP ACCESS to a function in the workspace is deny-by-default and needs all three: grants.bases includes the site, accessRules.execute allows the caller, and accessRules.runBy.pages is true; the site then calls functions.invokeAccount("<name>", params). A function in the workspace uses the workspace's secrets (automations_setEnvVar), a site's function its site's (site_createEnvVar): no fallback between them. A save is a draft (who runs a draft: functions_create). On a function with "Runs as Admin" switched on a change to its description, or a removal, applies at once, and a change to its code or definition is saved at once as a draft, each with a notice and an Undo; any other change waits for a person: the answer carries pendingChange (a card to tap, its approveLink) and nothing changes until they allow it (pendingChanges_dismiss cancels it). From the AI, isActive true with a live trigger is a card; send it alone. An AI agent can't change a function's grants, connections or declared kind (toolSpec.kind), nor change one with "Runs as Admin" switched on or one that reaches beyond the agent's own grants. Deny by default: a function with no access rule is refused for site users on every route, a page-started run reads only what that person may read ("Runs as Admin", and any change to a function that has it, waits for a person to allow its card), and a function that lives in a site uses only its site's own base. Read getCodeGuide topic "functions" for the full rules.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

newNamestring

Its new name (rename): 1 to 100 characters, no ':' or '%', unique where it lives whatever the capital letters.

descriptionstringnull
summarystring

Its one-line summary (a code function, wherever it lives): at most 500 characters; a longer one is refused and nothing is changed.

codestring

A code function's new body.

definitionobject

A data function's new definition (re-checked on save).

isActiveboolean

A code function: switched on (true) or off.

timeoutinteger

A code function's time limit in ms (1000 to 840000). A function may run up to 14 minutes (30 seconds when none is set). Runs started by a schedule, a flow, an agent or the queue (and account events and mailhooks) can use all 14 minutes, flows and agents within their own time limits; a call that waits for its answer, like a site page's call, cannot: a site's own address cuts a silent call after about 100 seconds.

maxRetriesinteger

Retries when an automation runs it and it fails. 0 = run once; more only for work that is safe to run twice.

grantsobject

What it may use, sent WHOLE (what you leave out is removed): bases, databaseIds, connections, serenitiesTools. A function that lives in a site holds only connections here (it reads its own site's base through ctx.tables).

connectionsarray

Its "Authorised connections" on their own, any code function: [{ id, tools? }], the same list as grants.connections; replaces that list and keeps the rest of its grants; [] = none. Never together with grants.

accessRulesobject

Who may call it: { execute, runBy }.

runAsstring

A data function only: "member" = the caller's own row permissions.

Allowed values: member, service

toolSpecobjectnull

Its MCP-tool schema, changed together with the code; null removes it.

exposedboolean

true = automations and AI may call it as a method.

adapterSpecany

Any code function (in the workspace or in a site): the spec that describes it as a payment provider, kept with the code. Once a version carrying it is published, someone with the permission "Offer functions as payment providers to sites" can offer the function as a payment provider to sites of the workspace (functions_offerAsPaymentProvider; no offer = not available, even to the function's own site), and each site then switches it on as a second step: site.listPaymentAdapters lists it (kind "function") and site.setPaymentAdapterConfig switches it on or off and between test and live, on the Payments tab, in the chat or over MCP (a person enters the keys its spec declares there, per test and live mode, with config and keysMode; the function uses them through ctx.secrets.ref('<field key>') once that name is on its own secrets list with the hosts it may go to, and only in a payment run, never as values). Once it is a provider, changes to the function need the same permission: anyone else's change waits on a card for someone who has it to allow. List the APP_ settings it relies on in its secrets list: a setting it lists is changed by hand (by someone without that permission, on a card the same way) or by its own code while no other such function lists it, and any other function's ctx.env.set of that setting is refused at the run, with nothing written. A setting it does not list is not protected. A built-in key such as pesapal is never taken over, and the function is started only through the one platform door. It never grants access by itself: the platform does, once, after verify confirms. A PaymentAdapterSpec { key, name, regions, amountEncoding, initiationShapes, confirmationStrategies, credentials: [{ key, label, secret?, placeholder? }], capabilities: { recurring, refund, webhook }, beta? }, at most 32 KB; credential fields are names only, never a value. Saved with the code as a new draft (publish to make it live); null takes it off.

seenUpdatedAtstring

The function's updatedAt as you last read it (functions_get, or your last save's answer): the save is refused if it was saved since. Leave it out if you haven't read it.

seenVersionstring

A data function: the `version` functions_get answered ("Runs as Admin" is switched on only for that version).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/update \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/delete

Delete one function permanently, wherever it lives, a code or a data function (its runs and versions go with it). Name it by id (alone), or by name (+ projectId for a site's). Act only on what the person named or picked.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/delete \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/invoke

Run a function once and return its result, wherever it lives. Name it by id (alone), or by name (+ projectId for a site's); params? is the input it receives. A flow step names it by id only (from functions_list). It runs for real: one that sends or writes only when the person asks. It runs as the workspace (the owner's side): it does NOT prove what a visitor or member may do; check the function's access rule and the tables' rules for that. A run refused before it started (a free plan, a function switched off; for an agent, one never published) says nothing ran: fix the cause and call again; a run that started and failed says it may have run. Returns its answer (a function in the workspace: { success, data, runId, executionTime }) and, at a person's own door, its logs: the console lines it wrote (secrets hidden; on a failure they follow the error). Who started it is passed to the code as data (ctx.run.startedBy: kind, and a member's id, name and role, and their email in the workspace's own functions (not an installed app's), or the agent and the person behind it, or the function that called it and who is behind that), never as rights.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

paramsobject

The input it receives as params (an object).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/invoke \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/publish

Publish a function's draft: it becomes the live version every run runs from the next run on (a run already going finishes on its own). Name it by id (alone), or by name (+ projectId for a site's), and versionId (optional: the draft, from the save's draftVersionId or functions_listVersions; leave it out and the function's newest draft is published, and if there is no unpublished draft you are told so and nothing changes). Every save of a function's code, definition or tool spec is a draft (who runs a draft: functions_create). Only a person who may change functions publishes or rolls back (the dashboard, their own AI chat or MCP); an AI agent or an automation saves drafts only. On a function with "Runs as Admin" switched on the answer is a card (pendingChange, approveLink) the person taps; nothing goes live until they do. Answers { versionId, number, publishedBy, publishedAt }.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

versionIdstring

The draft to make live (its id from functions_listVersions). Leave it out to publish the function's newest draft.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/publish \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/rollBack

Roll a function back: an earlier version that was live before becomes live again (no new version; an open draft is kept). Name it by id (alone), or by name (+ projectId for a site's), and versionId (the earlier version, from functions_listVersions). Only a person who may change functions rolls back; an AI agent or an automation never does. On a function with "Runs as Admin" switched on the answer is a card (pendingChange, approveLink) the person taps. Answers { versionId, number, publishedBy, publishedAt }.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

versionIdstringrequired

The earlier version to make live again (from functions_listVersions).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/rollBack \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/listVersions

List a function's versions, newest first: the draft (the latest save, waiting for a person to publish it), the live version (what every run runs) and the earlier ones that were live before. Name it by id (alone), or by name (+ projectId for a site's). Answers { versions: [{ id (the versionId functions_publish and functions_rollBack take), number, state (draft | live | archived), isLive, writtenBy, createdAt, publishedBy, publishedAt, linesChanged }] } and never the code.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/listVersions \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/setCapabilities

Prepare a function's powers ("email", "env", "users", "entitlements", "social", "agents"). Name it by id (alone), or by name (+ projectId for a site's), and send either capabilities (the whole list to keep) or remove (only these taken away). Giving a power waits for a person: the answer carries pendingChange (a card they tap, its approveLink) and nothing changes until they allow it. Never say a power is on before the person allowed it. "Runs as Admin" is no longer a power: adding "service" is refused (nothing changes, no card); prepare "Runs as Admin" with functions_setIdentityMode instead. A function that already holds "service" may keep it or have it taken away (at once, with a notice).

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

capabilitiesarray

The whole list of powers to keep.

removearray

Only these powers taken away (instead of capabilities).

seenVersionstring

The `version` functions_get answered: "Runs as Admin" is switched on only for that version.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/setCapabilities \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/setSecrets

Prepare a function's list of secrets (a function in the workspace: the workspace's secrets; a site's function: its site's). Name it by id (alone), or by name (+ projectId for a site's), and send secrets (the WHOLE list; [] = none), each { name, hosts (where it may be sent; none = only to check signatures with ctx.secrets.verifyHmac), keyFormat? ({ encoding: utf8|base64|hex, prefix? }), replyMayEmbed? (true only when a service on those hosts answers with a token that carries the secret inside it, e.g. a payment provider's auth token: that reply then reaches the code whole; logs, results and errors still hide it) }. The code never sees a value: it uses ctx.secrets.ref(name). A new secret, host or key format, or replyMayEmbed turned on, waits for a person: the answer carries pendingChange (a card they tap) and nothing changes until they allow it; taking one away applies at once with a notice and an Undo. A list never sends a secret beyond the secret's own allowed hosts. Use only when the user asks for it. An AI agent or an automation is refused: a list is a person's.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

secretsarrayrequired

The WHOLE list ([] = none): each { name, hosts, keyFormat?, replyMayEmbed? }.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/setSecrets \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/setTableGrants

Prepare a code function's table access: what it may do on named tables beyond what a visitor may, whoever starts it. Name it by id (or name, + projectId for a site's); send tables, the WHOLE list ([] = none): { tableId, actions (create|read|update|delete), fields? (field ids), where? ({ kind: "cond", field, op: "eq"|"in", value } or { kind: "and", children }) }. Adding waits for a person (pendingChange card; delete is high risk); narrowing applies at once with Undo. A read grant lets the function link to any row it covers: check link ids taken from a caller.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

tablesarrayrequired

The WHOLE list ([] = none).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/setTableGrants \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/offerAsPaymentProvider

Prepare offering a payment-provider function (a code function whose PUBLISHED version has an adapterSpec) to sites of this workspace, so each site may switch it on in its Payments settings (site_setPaymentAdapterConfig; offering alone takes no payment). Params: functionId (from functions_list), projectIds (1 to 25 sites, from site_listProjects). Needs the permission "Offer functions as payment providers to sites"; from you it is a card a person taps, nothing changes before. All or nothing; a site already offered it is left as it is; at most 25 per site. A draft-only provider is refused: publish it first. An offer of a function that lives in ANOTHER site is stored but never takes this site's payments: make it a function in the workspace instead, and never report such an offer as working.

Parameters

functionIdstringrequired

The payment-provider function's id (from functions_list).

projectIdsarrayrequired

The sites to offer it to (their projectIds from site_listProjects), 1 to 25, all of this workspace.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/offerAsPaymentProvider \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "functionId": "example",
  "projectIds": {}
}'
POST
/api/v1/functions/withdrawProviderOffer

Prepare to stop offering a payment-provider function to one site: its NEW checkouts no longer use it (a payment already started is still checked). Params: functionId, projectId. Needs the same permission as functions_offerAsPaymentProvider; from you it is a card a person taps. Withdrawing one not offered changes nothing.

Parameters

functionIdstringrequired

The payment-provider function's id (from functions_list).

projectIdstringrequired

The site to stop offering it to (its projectId from site_listProjects).

Example Request

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

Prepare a function's "Runs as Admin" switch. Off it reads "Runs as whoever starts it" (the default). Name it by id (alone), or by name (+ projectId for a site's), and mode (the on value, or "as_set_up" for off; see its values) and seenVersion (functions_get's version; needed to switch it on). On: This function is not held to what a visitor may see or change: it can read and change every row of your site's own tables and files, with the data rights an Admin has. It never gets people, billing or settings rights, and it still only uses what you gave it (connections, secrets, tools). It keeps running if people leave. Switching it on is high risk: the answer carries pendingChange (a card, its approveLink) and nothing changes until a person allows it, whoever asks (your own AI included). Only an Owner or an Admin can allow it. Switching it off waits for one tap on its card too. Never say it is on before the person allowed it. Use only when the user asks for it.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

modestringrequired

"workspace" = on: "Runs as Admin" (the function is not held to what a visitor may see or change); "as_set_up" = off: "Runs as whoever starts it" (the default).

Allowed values: as_set_up, workspace

seenVersionstring

The `version` functions_get answered (needed to switch it on).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/setIdentityMode \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/listRuns

Run history of one function, newest first. Name it by id (alone), or by name (+ projectId for a site's); limit? (default 50, at most 200), before? (the id of the oldest run you already have, for the runs older than it; it must be a run of this function). Each run: id, status (running | success | error), source (what started it), startedAt, finishedAt, durationMs, error (the one plain line it stored, never a stack trace), startedBy (who or what started it, in words). Read one with functions_getRun.

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

limitinteger

How many, newest first (default 50, at most 200).

beforestring

The id of the oldest run you already have; answers the runs older than it.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/functions/listRuns \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "projectId": "example"
}'
POST
/api/v1/functions/getRun

One run of one function. Name the function by id (alone), or by name (+ projectId for a site's), and runId (from functions_listRuns): another function's run is not found. Returns the fields functions_listRuns gives, plus functionId, functionName, projectId, scheduleId and, at a person's own door, log (its console lines, secrets hidden; only a function's latest runs keep them).

Parameters

idstring

The function's id: any function of the workspace, wherever it lives.

namestring

Its exact name instead of the id: alone, the function of that name in the workspace; with projectId, that site's.

projectIdstring

The site it lives in (from site_listProjects); omit it for a function in the workspace or with the id.

runIdstringrequired

The run's id (from functions_listRuns).

Example Request

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