Documentation · App Builder
Manifest reference
This page lists every property the manifest accepts, generated from the JSON Schema the App Studio and the runtime validate with. A property not listed here is rejected. For how the parts work together, read the concept pages: Manifest, Data, Views and pages, Agents and automation.
Paths are relative to the section: items[] is one element of a list, {key} is any key of a map. Req. marks properties that must be present when their parent is.
The document
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
apiVersion | "webrobot.eu/v1alpha1" | yes | Version of the manifest format. Must be exactly webrobot.eu/v1alpha1; the platform refuses any other value when the app is saved. | |
kind | "VerticalApp" | yes | Type of the document. Must be exactly VerticalApp. | |
metadata | object | yes | Identity of the app: its slug, its name and short texts, its languages and its time zone. slug and displayName are required. | |
metadata.slug | string | yes | Unique identifier of the app: 3 to 40 characters, lower-case letters, digits and hyphens, starting with a letter and not ending with a hyphen. It gives the default address <slug>.webrobot.eu and keeps the app's data and sign-in sessions apart from every other app; when the app is saved it must match the slug of the app it is saved under. Values: pattern ^[a-z][a-z0-9-]{1,38}[a-z0-9]$. | |
metadata.displayName | string | yes | Name of the app as people see it: the browser tab title, the name in the header (unless branding.wordmark is set), the page footer, the sign-in email (cleaned to one plain line of at most 60 characters), payment items at checkout, and the default name of the phone app. | |
metadata.tagline | text | Short sentence about the app. The runtime uses it as the page's meta description (for search results and link previews), in the visitor's language. | ||
metadata.description | text | Longer description of the app. Accepted by the schema; not used by the runtime yet. | ||
metadata.organizationId | string | integer | Organization that owns the app. The platform records the owner when the app is saved and the runtime takes it from there; the runtime does not read this field. | ||
metadata.langs | list of lang | Languages the app is offered in (two-letter codes, at least one, no duplicates). When it lists more than one, the header shows a language switch; a visitor gets the language they chose, else their browser's language if listed, else defaultLang. Without langs, the app has only defaultLang (default en). The runtime's own interface texts exist in English and Italian; other languages use English for them. Values: min items 1. | ||
metadata.defaultLang | lang | Language used when the visitor's language is not one of langs, and for messages the app sends on its own (emails, notifications, scheduled reports). Must be one of langs. Default: the first entry of langs; where neither is set, en. | ||
metadata.timezone | string | IANA time zone, e.g. Europe/Rome. The runtime uses it as the time zone of spec.serviceHours when that block sets none (default Europe/Rome). Cron expressions of schedules and triggers are evaluated in UTC, not in this zone. | ||
metadata.referenceOf | string | Only for reference manifests that describe an app built by hand: what that app is. Accepted by the schema; not used by the runtime. |
spec.pattern
enum · required. The kind of app: report = a form starts an agent run that produces a report; chat = a conversation with an agent, one background run per message; dashboard = scheduled agents or jobs fill data that users only read; pipeline = an agent sets up a data pipeline, the app runs it and reports on the dataset. Required. It describes the design; the runtime does not change its behaviour on it — what the app shows comes from views and agents. Values: report, chat, dashboard, pipeline.
spec.host
string. Full host name the app answers on, instead of the default <slug>.webrobot.eu (the app still answers on its default address too). Links in the emails the app sends and the address the phone app opens use this host. Put customer domains in domains, not here.
spec.domains
list of string. Customer domains that serve this app, e.g. app.example.com. Each one needs a DNS CNAME record pointing at the app's address (<slug>.webrobot.eu); the platform routes the domain to the app and requests its TLS certificate when the app is published.
spec.branding
object. The look of the app: colours, fonts, logo, name in the header, buttons and page width. The runtime turns it into CSS variables on every page; anything left out keeps the runtime's default look.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
theme | enum | Colour theme. light (or not set): palette and tokens are used. dark: paletteDark and tokensDark replace them (only when paletteDark is set). auto: follows the device's light/dark setting and requires paletteDark. Values: light, dark, auto. | ||
palette | palette | The four main colours of the app. A colour left out keeps the runtime default (primary #1f2a44, accent #2563eb, background #f7f8fa, foreground #161b26). The phone app also uses them: background for the status bar and splash screen, primary for the icon background. | ||
paletteDark | palette | The colours for the dark theme, used with theme: dark, or with theme: auto when the device is in dark mode. Required when theme is auto. Its background is also the dark splash-screen colour of the phone app. | ||
fonts | object | Google Fonts families for the app's text. Each name may contain only letters, digits and spaces (at most 41 characters); other names are ignored. The fonts are loaded in weights 400 to 900. | ||
fonts.body | string | Font family of the body text, e.g. Inter. Default: the system font. | ||
fonts.display | string | Font family of headings and of the app name in the header. Default: the body font. | ||
fonts.mono | string | Monospace font family. The runtime loads it from Google Fonts but no page style uses it yet. | ||
logo | string | Logo shown before the name in the header, and used for the phone app's icon. Either inline SVG markup (starting with <svg, at most 20,000 characters, sanitized: scripts and unsafe attributes are removed) or an https:// image URL; anything else is ignored. | ||
tokens | map of color | Extra named colours, each published as the CSS variable --<name> (underscores become hyphens; names up to 41 characters, values #rrggbb). The runtime's styles read these names when set: header, band, band-glow, heading, card, card-line, eyebrow, soft, button-ink. Any token can also be referenced by wordmark[].color, button and the inline styles of sections. | ||
wordmark | list of object | The app name in the header written in up to 4 parts, each in its own colour (e.g. two words in two colours). When set, it replaces displayName in the header. Values: max items 4. | ||
wordmark[].text | string | yes | Text of this part (at most 40 characters). Values: max length 40. | |
wordmark[].color | string | Name of a palette colour or token for this part (e.g. accent, or a key of tokens); it is applied as var(--<name>). Without it, the part has the header's default colour. Values: pattern ^[a-zA-Z][a-zA-Z0-9-]*$. | ||
byline | text | Small text shown after the name in the header, e.g. by Example Ltd. | ||
button | string | Palette colour or token used for the main buttons, the chat bubbles of the user and the outline of secondary buttons, e.g. primary. Default: accent. Values: pattern ^[a-zA-Z][a-zA-Z0-9-]*$. | ||
width | enum | Maximum width of the page content: normal (default) = 1080px; wide = 1200px. Values: normal, wide. | ||
tokensDark | map of color | The values of tokens for the dark theme (theme: dark, or theme: auto on a device in dark mode). Applied only when paletteDark is set. | ||
headingWeight | enum | Font weight of headings (h1–h4): 400, 500, 600, 700, 800 or 900. Default 700. Values: 400, 500, 600, 700, 800, 900. | ||
headingTracking | enum | Letter spacing of headings: normal (default) or tight (letters slightly closer, -0.02em). Values: normal, tight. | ||
brandWeight | enum | Font weight of the app name in the header: 500, 600, 700, 800 or 900. Default 700. Values: 500, 600, 700, 800, 900. | ||
buttonShape | enum | Corners of the buttons, chips and chat input: pill (default, fully rounded), rounded (10px radius) or square (4px radius). Values: pill, rounded, square. | ||
ghostButton | enum | Style of secondary buttons: outline (default) = transparent with text and border in the button colour; neutral = card background, normal text colour and a grey border. Values: outline, neutral. |
spec.auth
object. How people sign in, what visitors who are not signed in may use, and the roles of the app.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
method | enum | "magic_link" | Sign-in method. magic_link (default): the person enters their email and receives a one-time link and a 6-digit code, both valid for 15 minutes (the code dies after 5 wrong tries); the session lasts 30 days. none: visitors can open every page without signing in and the header shows no Sign in button. Values: magic_link, none. | |
public | boolean | When true, visitors who are not signed in can open every page of the app (a page's roles apply only to signed-in users). What a page shows still follows the data rules: visitors never see records that belong to a user. Default false. | ||
anonymous | object | What visitors who are not signed in may use, when public is not set: the pages listed in views, and the agents listed in agents. | ||
anonymous.agents | list of key | Agents marked as used by visitors without signing in. Each must be an agent key. Their app tools are restricted: no tool may reach a collection ownedBy: org, write a collection ownedBy: app or shared, send data to an external service (http tools other than GET) or use the user's own credential; validation refuses such tools and the runtime blocks them. Starting a run or sending a chat message still requires signing in. | ||
anonymous.views | list of key | Pages visitors can open without signing in. Each must be a view key. A form view listed here accepts submissions from visitors only into a collection ownedBy: org (the owner's inbox), at most 5 per hour from the same IP address, without file attachments. | ||
roles | list of object | The roles of the app. A signed-in user holds one role, resolved on every request in this order: the admin_emails role if their email is on the app's admin list; else a role stored on their user record; else a derived role whose collection names them; else the signup role (if none is declared, the role is user). Roles are used by views, fields, collection access rules, approvals, limits and notifications. | ||
roles[].key | key | yes | Identifier of the role, referenced elsewhere (e.g. roles: [admin] on a view, role:<key> in notifications). | |
roles[].label | text | Display name of the role. Not shown by the runtime yet. | ||
roles[].assignedBy | enum | How a user gets the role. admin_emails: users whose email is on the app's admin list (managed outside the manifest); this role is the app's admin — it reaches all data and is exempt from limits and plan gates. signup: every user who signs in without another role (only the first signup role counts). derived: held while a record of a collection names the user's email (see from); it takes the place of the signup role, and the user keeps the signup role's pages too. admin / invite: the role is honoured when it is stored on the user's record; the runtime has no page or API to grant it yet. Values: admin_emails, admin, signup, invite, derived. | ||
roles[].from | string | list of string | For assignedBy: derived only: where the user's email is looked up, as collection:<name>.<emailField> (or a list of them: any match is enough). The field may hold one email or a list of emails; comparison ignores case. When several derived roles match, the first in the manifest's order wins. |
spec.limits
list of object. Rate limits and quotas the runtime enforces. A request over the limit is refused with HTTP 429 (limit reached: …). App admins are exempt from the limits on runs and on records they create. Every window is counted backwards from now (sliding).
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].action | string | yes | What is counted. run: runs a user starts from the form. agent:<key>: runs of that agent a user starts, and also starts of that agent by triggers, approvals and dates. agents: every agent start caused by an event (triggers, approvals, dates). create:<collection>: records a user creates, through a form or an agent's write/append tool. chat and login are accepted but not enforced from here; chat and sign-in have fixed limits of their own (chat: 30 messages per hour per user and 60 per IP; sign-in: 10 requests per hour per IP and 3 per email address). | |
[].per | enum | "user" | Whose actions are counted together. user (default): each user separately — the only value used for run, agent:<key> on runs a user starts, and create:<collection>. app: all starts of the app together — used only for agent starts caused by events. ip and org are accepted but not enforced yet. For event-started agents, a limit applies only when per is written explicitly as user or app. Values: user, ip, org, app. | |
[].max | integer | yes | Maximum count in the window (at least 1). For run, agent:<key> and create:<collection>, a plan in plans can raise it. Values: ≥ 1. | |
[].window | enum | yes | Period counted: minute, hour, day (24 hours), month (30 days) or total (ever: a quota, e.g. at most N records in the plan). total is not applied to agent starts caused by events. Values: minute, hour, day, month, total. | |
[].roles | list of key | Applies only to users holding one of these roles (empty = everyone). Checked only for run and agent:<key> on runs a user starts; create:<collection> and event-started agents ignore it. Visitors cannot start runs, so anonymous here has no effect yet. | ||
[].rolling | boolean | Sliding window (the last 24 hours) instead of the calendar one. Accepted by the schema but ignored: the runtime always counts a sliding window back from now. | ||
[].plans | map of integer | A different maximum per plan or pack key: a user who holds that plan gets this value instead of max; -1 = unlimited. With several plans the highest applies; a user with none gets max. Applied to run, agent:<key> on runs a user starts, and create:<collection> through agent tools; forms and event-started agents use max only. Each key must be a plan or pack of spec.billing. |
spec.agents
list of object · required. The app's agents (at least one). Each one is an agentic profile that the runtime starts for a form run, a chat message, a schedule, a trigger, a template instance or a delegation. Agent keys are referenced as agent:<key> in view sources, billing.costs and limits. Values: min items 1.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique key of the agent. Other parts of the manifest refer to it (agent:<key> sources and costs, start.agent, delegates, team steps, channels). At publish an inline agent becomes a profile named <slug>-<key>, and a delegation to it becomes the tool ask_<key> (hyphens become underscores). A team may not use the same key. | |
[].role | enum | "main" | Only main (the default) changes behaviour: a form run picks among the main agents (the first whose when matches, else the first main agent, else the first agent), and a chat view without a known agent falls back to the first main agent. The other values (designer, setup, analyst, helper, scheduled) are labels: the runtime treats those agents alike and starts them only when something names them (a schedule, a trigger, a template, a delegation, a chat view). Values: main, designer, setup, analyst, helper, scheduled. | |
[].description | string | What the agent does, in a sentence. Publishing uses it as the profile description (default <displayName> — <key>), and another agent that delegates to this one sees it in the description of its ask_<key> tool. | ||
[].profile | yes | The agentic profile the agent runs: exactly one of ref (an existing profile) or inline (a definition published with the app). The profile's own goal template may wrap the app's goal as {goal}. An agent with an inline profile cannot run until the app is published (the runtime answers 409 publish the app first). | ||
[].profile.ref | integer | string | Id or name of an existing agentic profile of the app's organization. Publishing also writes here the id of the profile it created from inline. The runtime starts this profile with the agent's goal. | ||
[].profile.inline | object | An inline agent definition (the Agent Studio contract; crews is required). At publish it becomes a profile named <slug>-<key>, created once and updated on later publishes; the app's own MCP endpoint (for appTools, delegates, awaits, memory) and the mcpServers are added to every crew; a definition without orchestration gets a DAG over its crews. Agents that are part of a team must be inline. | ||
[].when | string | Condition on the run form's values that selects this agent among the main agents, e.g. mode == 'market'. Supported syntax: field == 'x', field != 'x', field (truthy), !field, joined by && and ||; anything else is false. Only form runs evaluate it. | ||
[].goalTemplate | string | The task sent to the agent. {name} is replaced by a form field, a context key or a built-in: {<field>_label} (label of the chosen option), {<field>_text} (text extracted from an uploaded file), {date} (UTC, YYYY-MM-DD), {lang}, {user} (email), {role}; in a chat also {message}, {history} and {session}. {?name}...{/name} keeps the block only when name is non-empty, {!name}...{/name} only when it is empty; validation refuses unknown placeholders and unclosed blocks. Without it a form run sends one label: value line per filled field, and a chat sends the conversation so far and the new message. | ||
[].context | list of object | Extra values resolved when a form run starts, before any credit is held, and made available to goalTemplate under each entry's key. Only form runs resolve them (not chats, schedules, triggers or template instances). | ||
[].context[].key | string | yes | Placeholder name the value is put under, used in the goal as {<key>}. Lowercase letters, digits and underscores, starting with a letter. Values: pattern ^[a-z][a-z0-9_]*$. | |
[].context[].from | string | yes | Where the value comes from. collection:<name>.<field>: that field of THE record (the one chosen in a form field fed by optionsFrom: collection:<name>, else the user's latest record of a user-owned collection). collection:<name>: the records the user may read, as JSON lines (at most 30 records, 8000 characters). user.<field>: a field of the signed-in user (email, name, plans…). slot:<key>: the Python slot runs on {values, lang}; an object result adds its fields to the goal values, anything else goes under key. session, page and derived:<extension> are accepted by the schema but not resolved by the runtime yet. | |
[].variables | map of string | Profile variables the app sets on each form run: {profileVar: template}. Each value is rendered like a goal template (form and context values, {lang}, {user}) and sent to the profile as an input next to the goal. Only form runs send them. | ||
[].startOptions | object | Extra fields for the agent's start. The keys forceReauthor, llmProvider, engine, camoufoxMode, ttlSeconds, activeDeadlineSeconds and clusterSelector are start options; any other key (e.g. current_yaml) travels as an input next to the goal. Applied to form runs, chat messages and schedules; not to triggered, delegated or template-instance runs. | ||
[].appTools | list of appTool | Tools the app itself gives this agent, served by the runtime's MCP endpoint (/api/mcp). Publishing gives each agent its own URL and token, so an agent sees only its own tools plus the ones its edges generate. A tool name may appear in several agents only if it does the same thing (same action, target and limits). Tools with extension are not served. | ||
[].output | enum | "markdown" | The shape of the agent's answer: markdown (default), markdown+json, json, pipeline_yaml, final_block. Accepted by the schema; not used by the runtime yet. How a result becomes a record is set by writesTo.parse. Values: markdown, markdown+json, json, pipeline_yaml, final_block. | |
[].resultSchema | object | JSON Schema of the structured part of the output. Accepted by the schema; not used by the runtime yet. | ||
[].writesTo | object | Turns each finished scheduled, triggered or template-instance run of this agent into a record of collection (form runs and chat messages do not write records). The record holds the parsed fields, report (the answer from its first heading on), completedAt and date, plus the collection's field defaults; it carries the event's user and, for a template instance, the instance. Writing it fires the collection's insert triggers. | ||
[].writesTo.collection | string | yes | The declared collection the record is written to (not a reserved one). A trigger on this same collection that starts this agent must have a where filter (or op: update), or validation refuses it. | |
[].writesTo.parse | enum | "whole" | How the answer becomes fields. whole (default): no extra fields, only report, completedAt, date. markdown_sections: each ## Heading section becomes a field named after the heading (lowercase, non-alphanumerics as _). json_last and final_block (same behaviour): the fields of the last fenced ```json block of the answer. Values: markdown_sections, json_last, final_block, whole. | |
[].writesTo.keyBy | string | Field of the built record used as its id, e.g. date: a later run with the same value replaces the record (one signal per day). Without it, or when the field is missing, the id is <date>_<timestamp>. Ignored for template-instance runs, which always get one record per run. | ||
[].limits | object | Run limits for the agent (turns, budget, time). Accepted by the schema; not used by the runtime yet. The app's own limits on starts are spec.limits (agent:<key>, agents, run). | ||
[].limits.maxTurns | integer | Maximum number of agent turns (minimum 1). Accepted by the schema; not used by the runtime yet. Values: ≥ 1. | ||
[].limits.maxBudgetUsd | number | Maximum spend of one run, in US dollars. Accepted by the schema; not used by the runtime yet. Values: ≥ 0. | ||
[].limits.timeoutSeconds | integer | Maximum duration of one run, in seconds (minimum 30). Accepted by the schema; not used by the runtime yet. Values: ≥ 30. | ||
[].mcpServers | list of object | External services (POS, delivery, calendar…) as MCP servers, at most 10. At publish they are added to every crew of the agent's inline profile (a ref profile is not changed). Never put secrets here: a header value may reference ${VAR}, a credential of the organization, and validation refuses a header that looks like a literal secret. Values: max items 10. | ||
[].mcpServers[].name | string | yes | Name of the server in the agent's tool list: lowercase letter first, then lowercase letters, digits, _ or -, at most 31 characters. A crew server with the same name is replaced. Values: pattern ^[a-z][a-z0-9_-]{0,30}$. | |
[].mcpServers[].url | string | yes | The server's MCP endpoint; must start with https://. Values: pattern ^https://. | |
[].mcpServers[].headers | map of string | HTTP headers sent to the server, e.g. {"Authorization": "Bearer ${POS_API_KEY}"}. Use ${VAR} references only: validation refuses a value that still has a run of 20 or more letters, digits, _ or - once the ${VAR} references are removed. | ||
[].mcpServers[].allow | "all" | list of string | Which of the server's tools the agent may use: all (the default when omitted) or a list of tool names. | ||
[].delegates | list of string | Agents this one can hand a sub-task to and wait for. Each becomes the tool ask_<agent> (args: task, at most 8000 characters); the runtime starts that agent and waits up to 150 seconds for its answer, else returns still working with the run id. The target must be published; an agent cannot delegate to itself and delegation loops are refused. | ||
[].awaits | list of string | Approvals this agent may ask for. Each becomes the tool request_<approval> (args: summary, at most 500 characters, and request, an object of at most 32,000 characters as JSON); it returns at once with status pending, and a trigger on the approval's decision resumes the work. | ||
[].memory | enum | "none" | Persistent notes the agent keeps. none (default): no memory. user: one note per app user. instance: one note per template instance (a template must instantiate this agent). The notes (at most 4000 characters) are added to the agent's task when a user is known, and the agent replaces them with the generated remember tool. Values: none, user, instance. |
spec.inputForm
object. The form that starts a run (pattern report): its fields become the values of the main agent's goal. It is shown on views of type new_run.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
title | text | Heading of the run form, shown when the new_run view has no title of its own. | ||
fields | list of field | Fields of the run form. Their values fill the {field} placeholders of the agent's goalTemplate; a select also provides {<field>_label} (the chosen option's label) and a file field {<field>_text}. Without a goalTemplate, the goal is one label: value line per filled field. | ||
examples | list of object | Prefilled example inputs, meant to be shown as chips. Accepted by the schema; not used by the runtime yet (chat views have their own examples). |
spec.data
object. The app's data: platform data jobs whose datasets pages can show, the app's own record collections, and the API keys users connect for external services.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
jobs | list of object | Data jobs of the platform the app uses. A job is reached by its key from a page data block (source: job:<key>), a schedule (job) or a trigger (start.job); it must have projectId and jobId (set by hand or filled in when an inline pipeline is published), otherwise the block shows "Job not linked." and a start is skipped. | ||
jobs[].key | key | yes | Name of the job inside the app (lowercase letters, digits, _ and -, starting with a letter). Referenced as job:<key> in data blocks and as job in schedules and triggers; validation refuses a reference to an unknown key. | |
jobs[].description | string | Free text for the people who read the manifest. The runtime does not show or use it. | ||
jobs[].projectId | integer | string | Id of the platform project that holds the job. With jobId, the runtime uses it to start the job and to read the dataset of its latest task. Publishing an inline pipeline sets it. | ||
jobs[].jobId | integer | string | Id of the platform job. Required, with projectId, for the job to be started or read; publishing an inline pipeline sets it. | ||
jobs[].pipeline | object | Where the job's pipeline comes from. Only inline is acted on: publishing creates (or updates, by name) a project named after the app slug and a pipeline and job named <slug>-<key>, writes their ids into projectId/jobId and replaces inline with ref. fromAgent, runBy, datasetMatch and extension are accepted by the schema but not used by the runtime yet. | ||
jobs[].pipeline.ref | integer | string | Name or id of an existing pipeline. Publishing writes ref: <slug>-<key> after creating an inline pipeline. The runtime does not resolve ref by itself: to use an existing job, also set projectId and jobId. | ||
jobs[].pipeline.inline | string | The pipeline as YAML text: a list of stages, a pipeline spec, or a whole kind: Pipeline document (its spec is kept). On publish it is applied to the platform and the job's ids are filled in; anything else fails the publish with "inline pipeline is not YAML stages or a pipeline spec". | ||
jobs[].pipeline.fromAgent | string | Key of an agent meant to produce the pipeline YAML. Accepted by the schema; not used by the runtime yet. | ||
jobs[].pipeline.runBy | string | Key of an agent meant to build and run the job itself, the app then finding the dataset afterwards. Accepted by the schema; not used by the runtime yet. | ||
jobs[].pipeline.datasetMatch | string | With runBy: a name pattern to find the agent's dataset. Accepted by the schema; not used by the runtime yet. | ||
jobs[].pipeline.extension | string | Name of custom code meant to compose the pipeline. Accepted by the schema; not used by the runtime yet. | ||
jobs[].params | object | Pipeline variables bound to form fields, as {variable: '{field}'}. Accepted by the schema; not used by the runtime yet: jobs are started without parameters. | ||
jobs[].perRecord | string | collection:<name>: meant to create one job (and schedule) per record at run time. Validation checks that the collection is declared; not used by the runtime yet. | ||
jobs[].schedule | string | A cron expression meant to run the job on a timer. Accepted by the schema; not used by the runtime yet: to run a job on a timer, use spec.schedules with job, or a trigger with on.cron and start.job. | ||
jobs[].ingestTo | "none" | object | list of object | Where the job's rows were meant to go after each run (none, one target, or a list of targets). Accepted by the schema; not used by the runtime yet: pages read a job's latest dataset directly through a data block. | ||
jobs[].ingestTo.kind | enum | yes | collection: rows go into an app collection; search: rows go into a search index. Accepted by the schema; not used by the runtime yet. Values: collection, search. | |
jobs[].ingestTo.target | string | yes | Collection name (kind collection) or search index name (kind search). Accepted by the schema; not used by the runtime yet. | |
jobs[].ingestTo.mapping | map of string | Column mapping as {targetField: sourceColumn}. Accepted by the schema; not used by the runtime yet. | ||
jobs[].ingestTo.keyBy | string | The field that identifies a row, so a new run would update rather than duplicate it. Accepted by the schema; not used by the runtime yet. | ||
jobs[].ingestTo.incremental | boolean | Whether only new rows would be copied on each run. Accepted by the schema; not used by the runtime yet. | ||
jobs[].ingestTo.retentionDays | integer | Days the copied rows would be kept (at least 1). Accepted by the schema; not used by the runtime yet (for records, see collections[].retentionDays). Values: ≥ 1. | ||
collections | list of object | The app's own record collections, kept in the app's store. Every reference to a collection anywhere in the spec (collection:<name> sources, tools, triggers, forms) must name one declared here, and the runtime refuses to read or write an undeclared one. Runtime names such as users, runs, files, credentials or approvals are reserved and refused. | ||
collections[].name | key | yes | Name of the collection (lowercase letters, digits, _ and -, starting with a letter). Must be unique and must not be a reserved runtime name. New record ids start with its first three letters. | |
collections[].description | string | Short text shown next to the collection on the admins' data page. | ||
collections[].fields | list of field | The fields of a record. They drive the form views (and the admins' data page and CSV import, where file fields are left out), the argument schema of the agents' write and append tools, labels and option labels in data blocks, and the default values new records get. Agents' tools can still store fields that are not listed: the list is not enforced on their writes. | ||
collections[].ownedBy | enum | "user" | Who owns the records, which sets who can read them (default user). user: each record belongs to the user who created it and only that user reads and changes it. instance: like user, and an agent run of a template instance only reaches that instance's records; forms and trigger writes cannot target it. app and shared: one set of records every user (signed in or not, where the page allows it) can read; only admins add records through forms and the data page, agents write through their tools. org: the owner's back office: only admins read it; signed-in users and allowed visitors can submit records into it through a form but not read them. The app's admins read and change everything; access rules give other roles more. Values: user, org, app, shared, instance. | |
collections[].parent | string | Parent collection: records meant to live under one parent record. Accepted by the schema; not used by the runtime yet. | ||
collections[].sharing | list of enum | Per-record invitations (viewer, editor). Accepted by the schema; not used by the runtime yet: use access rules to let other users reach records. Values: viewer, editor. | ||
collections[].searchable | boolean | Marks the collection for search. Accepted by the schema; not used by the runtime yet. | ||
collections[].access | list of object | Rules that let users with a given role reach records they do not own (at most 10). A user holding role reads, and with can: [read, write] also changes, the records whose fields match where; no where means every record. Views, data blocks, the agents' app tools, agent context and selects fed by the collection all apply them. Validation refuses a rule for an unknown role, a rule without where for the role given at signup, and a read-only rule on an app or shared collection (everyone reads it already). Values: max items 10. | ||
collections[].access[].role | key | yes | The role the rule applies to: a key of spec.auth.roles (a user also matches through a signup role they still hold beside a derived one). Admin roles need no rule: admins reach every record. | |
collections[].access[].where | map of string | number | boolean | Which records the rule covers: every listed field must match (at most 4). "{user.email}" and "{user.id}" stand for the user's email and id; values that contain @ are compared ignoring case and also match a list field that contains them; other values must be equal as text. Without where, the role reaches every record. | ||
collections[].access[].can | list of enum | ["read"] | What the role may do on the matching records (default [read]): read lets it see them; write lets it change them (for example through an edit form or an agent's write tool). Values: read, write. | |
collections[].retentionDays | integer | Records older than this many days (1 to 3650) are deleted automatically, once a day by the runtime's scheduler, based on the record's creation time (or last update when it has no creation time); up to 5,000 records per collection per day. Values: ≥ 1; ≤ 3650. | ||
credentials | list of object | API keys the app's users connect on the account page (a view of type account is required when any api_key credential is declared). Keys are encrypted at rest, never shown again (only their last four characters), never put in an agent's goal; an app tool of action http with http.credential gets the key added to its request. Only kind api_key works today; oauth and mcp are not available yet. | ||
credentials[].provider | string | yes | Name of the service; an http app tool points at this credential with http.credential.provider. Each user (or the app, with scope org) keeps one key per provider. | |
credentials[].label | text | Name of the service shown on the account page (defaults to provider). | ||
credentials[].kind | enum | How the user connects (default api_key). api_key: the user pastes a key (8 to 4,000 characters, no spaces). oauth and mcp: not available yet; such entries are ignored by the runtime. Values: api_key, oauth, mcp. | ||
credentials[].url | string | kind mcp: the address of the user's MCP server. Accepted by the schema; not used by the runtime yet (mcp is not available). | ||
credentials[].allowTools | list of string | kind mcp: the tools of the user's MCP server the agents may call. Accepted by the schema; not used by the runtime yet. | ||
credentials[].scope | enum | "user" | Whose key it is (default user). user: each user saves their own key and the tool uses the key of the user it acts for; such a tool needs a signed-in user, so it cannot belong to an agent that visitors use without signing in. org: one key for the whole app, which only the app's admins can see on the account page, save or remove. Values: user, org. | |
credentials[].required | boolean | Marks the connection as needed by the app. Accepted by the schema; not used by the runtime yet: nothing forces the user to connect, and a tool that needs the missing key fails with "the user has not connected <provider>: ask them to connect it on their account page". | ||
credentials[].help | text | Where the user finds the key; shown under the service on the account page. | ||
credentials[].hostLabel | text | When set, the account page also asks for the user's own host (shown as the placeholder of that input), for tools whose URL starts with https://{host}. The host must match a wildcard entry of spec.egress.hosts (e.g. *.myshopify.com), otherwise saving is refused. |
spec.views
list of object. The pages of the app. Each view is opened at /v/<key>; the views a signed-in user may open (except report and run, and those with nav: false) form the menu. The home page is the view keyed home when there is one the visitor can open, otherwise the first menu view.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique name of the view: lower case letters, digits, _ and -, starting with a letter. The view is served at /v/<key>; the key home makes it the home page. Other parts of the manifest (children, page blocks, auth.anonymous.views, submit.redirect) refer to it by this key. | |
[].type | enum | yes | What the view is. new_run: the input form (spec.inputForm) that starts a run; report: where a finished run is shown (/r/<id> uses its title and printable; opening the view itself goes to the home page); run: opening it goes to the home page; history: the user's runs (sign-in required); chat: a conversation with an agent (signed-in users only); table, cards, list, chart: rows from source shaped by data; map: rows as markers; dashboard: children side by side; tabs: children as tabs; page: Markdown content and sections; form: adds or edits a record of collection; booking: free time slots to book; approvals: pending approval requests; instances: the user's agents made from a template; account: credit balance, packs and plans to buy, connected services and credit movements; admin: users, credits and latest runs, for the app's admins; review: not rendered by the runtime yet (the page says so). Values: new_run, run, history, report, chat, review, table, cards, chart, dashboard, tabs, account, admin, page, list, approvals, instances, form, booking, map. | |
[].title | text | Heading of the view and its label in the menu (plain string or one per language). In the menu a view without title shows its key. | ||
[].source | string | Where the rows come from. run (default for table, cards, list, chart and map): the signed-in user's runs, with the input form values as fields; job:<key>: the latest dataset of a data job in data.jobs, queried with the view's fields, filters, sort and limit (cached for 60 seconds); collection:<name>[.<path>]: records of a declared collection that the user may read (the .path part sets data.path); catalog[:<category>]: the platform's public source catalog (cached for 60 seconds); agent:<key>: for type chat, the agent that answers (default: the agent whose role is main). Names are checked at validation. | ||
[].param | string | Accepted by the schema; not used by the runtime yet. | ||
[].query | string | Accepted by the schema; not used by the runtime yet. Use data.filters to filter rows. | ||
[].columns | list of string | Short form of data.fields: the row fields to show as columns, in order, with default labels and formats. Ignored when data.fields is set. | ||
[].children | list of key | type tabs, dashboard or admin: keys of the views it contains, in order (each must exist). Children the user may not open are left out. A dashboard shows them side by side, tabs one at a time (?tab=<key>, default the first), an admin view below its own tables (never another admin view). Nesting is limited: a dashboard or admin view shows its children only when it is not itself inside another view. | ||
[].preview | object | Teaser for users without a plan: with unlessPlan set, users who do not hold that plan (admins excepted) see only the first rows rows, a line saying how many more rows the plan unlocks, no row buttons and no CSV export. | ||
[].preview.rows | integer | Rows shown to users without the plan. Default 3; 0 hides them all. Values: ≥ 0. | ||
[].preview.hideColumns | list of string | Accepted by the schema; not used by the runtime yet. | ||
[].preview.unlessPlan | string | Key of a plan or pack in billing; users whose plans include it see every row. Validation refuses a key that is not a plan or pack. Without it there is no teaser. | ||
[].placement | enum | "page" | Accepted by the schema (page, default, or floating, meant as a chat bubble on every page); not used by the runtime yet: every view is rendered as a page. Values: page, floating. | |
[].printable | boolean | type report: shows a Print button on the finished run's page. Default true. | ||
[].roles | list of key | Roles that may open the view (keys of auth.roles). Empty or absent: every signed-in user. A user matches with their role or one of their additional roles; app admins are not exempt, so list the admin role on pages admins use. Visitors who are not signed in see a view only when auth.public is true, auth method is none or the view is in auth.anonymous.views. | ||
[].nav | boolean | true | Whether the view appears in the menu. Default true. The menu is shown to signed-in users and never lists report or run views or views their role cannot open; a view with nav: false is still reachable by its URL. | |
[].content | text | type page: Markdown shown before the sections (plain string or one per language), rendered through the safe Markdown renderer. | ||
[].sections | list of section | type page: the blocks of the page, rendered top to bottom after content. See section. | ||
[].examples | list of text | type chat: example questions shown as chips before the first message (at most 8); clicking one sends it. Values: max items 8. | ||
[].placeholder | text | type chat: placeholder of the message box. Default: "Ask anything…" ("Scrivi la tua domanda…" in Italian). | ||
[].data | object | type table, cards, list, chart (and map, for filters, sort and path): how the rows from source are shown: fields, filters, grouping, order, limit, key numbers, chart type and row buttons. | ||
[].data.path | string | Dot path (at most two levels) to a list inside each row; the lists of all rows are flattened into the rows shown (for example assets of each signal). Applied before filters. With a view source written collection:<name>.<path> the runtime fills this from the source when it is not set. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
[].data.display | enum | How the rows are shown. Default: the view's type (table, cards or list); a view of type chart is always shown as chart. table (default rendering): one column per field; cards: a grid, first field as heading; list: one line per row, first field in bold; kpi: key numbers from kpis (shown even with no rows); bar: horizontal bars, first field = label, second = value; chart: an SVG chart of type chart. Values: table, cards, list, kpi, bar, chart. | ||
[].data.fields | list of object | The columns, in order (at most 12). Without fields the runtime shows the first 6 field names found in the rows. On a collection: source (without path) a field with no label takes the collection field's label, and a select field shows the option label instead of the stored value. Values: max items 12. | ||
[].data.fields[].key | string | yes | Field of the row to show, as a dot path of at most two levels (e.g. price or address.city). For a job source it must be a dataset column. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | |
[].data.fields[].label | text | Column heading (plain string or one per language). Default: the collection field's label on a collection source, otherwise the key. | ||
[].data.fields[].format | enum | How the value is shown. text (default): as is; a value shaped like a position ("lat,lng") becomes a map link, an object is shown as JSON, and in a table a text longer than 220 characters shows a plain excerpt with the whole text on hover. number: locale number, at most 2 decimals; money: amount in the app's billing.currency (default EUR), no decimals; percent: the value is already a percentage, shown signed and coloured (+12.5%); ratio: a fraction multiplied by 100 and shown as a percent (0.25 → +25%); date: day, short month, year; link: an https URL as a clickable shortened link (other values as plain text); badge: a pill; location: a "lat,lng" position as a map link. An empty value shows a dash. Values: text, number, money, percent, ratio, date, link, badge, location. | ||
[].data.filters | list of object | Conditions every row must meet (all of them, at most 8), applied before grouping, sorting and the limit. On a job: source they become the WHERE clause of the dataset query. Values: max items 8. | ||
[].data.filters[].field | string | yes | Field the condition reads, as a dot path of at most two levels. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | |
[].data.filters[].op | enum | yes | Comparison. = and != compare as text; >, >=, <, <= compare as numbers and drop rows whose value is not a number; contains: case-insensitive substring match. Values: =, !=, >, >=, <, <=, contains. | |
[].data.filters[].value | string | number | boolean | yes | Value compared with the field: text, number or boolean. | |
[].data.sort | object | Order of the rows, applied after filters and grouping and before the limit. Without it rows keep the source order (a run source is newest first; grouped rows are ordered by group value, ascending). | ||
[].data.sort.field | string | yes | Field to order by (dot path of at most two levels). Numbers compare as numbers, anything else as text. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | |
[].data.sort.dir | enum | desc (default) or asc. Values: asc, desc. | ||
[].data.limit | integer | Maximum number of rows (or groups) shown, 1–200. Default 50. Key numbers (kpis) are computed on these rows only. Values: ≥ 1; ≤ 200. | ||
[].data.kpis | list of object | display kpi: the key numbers, at most 6, each an aggregate over the rows. Without kpis one number is shown: the row count. Values: max items 6. | ||
[].data.kpis[].label | text | yes | Text under the number (plain string or one per language). | |
[].data.kpis[].agg | enum | yes | The aggregate: count (rows, no field needed), sum, avg, min, max (over the field's numeric values; non-numbers ignored, empty when none), last (the field's value in the first non-empty row in the current order). Values: count, sum, avg, min, max, last. | |
[].data.kpis[].field | string | Field the aggregate reads (dot path of at most two levels). Not needed for count. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
[].data.kpis[].format | enum | How the aggregate is shown: number, money (app currency, default EUR), percent, ratio (×100 as a percent), date, link, badge or text. Default: number for count, plain value for the other aggregates. Values: text, number, money, percent, ratio, date, link, badge. | ||
[].data.empty | text | Message shown when there are no rows (not for display kpi). Default: "No data yet." ("Ancora nessun dato." in Italian). | ||
[].data.chart | enum | display chart: the chart type. bar (default): grouped bars; line: lines with points; pie: one slice per row from the first series only (negative values count as 0); stacked: stacked bars (negative values ignored). The first field gives the labels, every other field a series. Values: bar, line, pie, stacked. | ||
[].data.groupBy | object | Groups the rows (after filters): one row per value of field (dates bucketed by day, week or month) with a count column and one column per aggregate in aggs; groups are ordered by value, ascending, then sort and limit apply. Use the group field, count and the agg keys as fields. minCount hides small groups; acrossUsers on a collection of user records aggregates every user's records anonymously (needs minCount ≥ 5; no record is ever shown). | ||
[].data.groupBy.field | string | yes | Field whose value forms the group (dot path). Rows with no value go to a group named "—". | |
[].data.groupBy.bucket | enum | Treats the field as a date and groups by day (YYYY-MM-DD), week (the date of that week's Monday) or month (YYYY-MM), in UTC. Rows whose value is not a date go to "—". Without bucket, every distinct value is a group. Values: day, week, month. | ||
[].data.groupBy.aggs | list of object | yes | The aggregate columns of each group (at most 8). count is always added. Values: max items 8. | |
[].data.groupBy.aggs[].key | string | yes | Name of the column the aggregate is written to; refer to it in fields, sort and kpis. Values: pattern ^[A-Za-z_][A-Za-z0-9_]*$. | |
[].data.groupBy.aggs[].agg | enum | yes | The aggregate over the group's rows: count (rows, no field needed), sum, avg, min, max (over the field's numeric values; non-numbers ignored, empty when none), last (the field's value in the first non-empty row in the current order). Values: count, sum, avg, min, max, last. | |
[].data.groupBy.aggs[].field | string | Field the aggregate reads (dot path). Not needed for count. | ||
[].data.groupBy.minCount | integer | Groups with fewer rows than this are left out (1–1000, default 1). Must be at least 5 with acrossUsers. Values: ≥ 1; ≤ 1000. | ||
[].data.groupBy.acrossUsers | boolean | On a collection: source whose collection is ownedBy: user: aggregates the records of every user, not only the viewer's, and shows only the groups (an anonymous benchmark). Validation refuses it on other sources and with minCount below 5; the runtime reads every user's records only when minCount is at least 5. | ||
[].data.actions | list of recordAction | Buttons on each row (at most 4): call, directions, share, add to calendar. Not shown on rows of a locked teaser. share and calendar add the matching permission to the phone app. Values: max items 4. | ||
[].approvals | list of string | type approvals: keys of the approvals (spec.approvals) the view lists. Default: all of them. Each user sees only the pending requests they may decide, plus the 20 latest decided. Unknown keys are refused at validation. | ||
[].template | string | type instances: key of the template (spec.templates) whose instances the user creates, runs, pauses and sees the latest result of. A user can have at most the template's maxPerUser instances (default 5). Required for this type: an unknown key is refused at validation. | ||
[].collection | string | type form: the declared collection the form writes. Visitors not signed in can send a form only when it is in auth.anonymous.views and the collection is ownedBy: org (at most 5 submissions per hour per address); a collection ownedBy: app or shared takes new records only from admins; an ownedBy: instance collection is refused. type booking: the collection of bookings, which must be ownedBy: user; each booking record gets start, end (ISO, UTC), date, resource (when there are resources), status (booked or cancelled), userId and bookedBy. | ||
[].fields | list of string | type form: names of the collection's fields to show, in order (default all of them). type booking: the collection's extra fields asked when booking (e.g. notes, phone); only text, number and boolean values are kept, text cut at 2000 characters. Every name must be a field of the collection. | ||
[].edit | boolean | false | type form: lets /v/<key>?id=<record> change an existing record the user may write (own record or an access rule with write). Default false: the form only creates records. | |
[].submit | object | type form: the button, the message after saving and the page to open next. | ||
[].submit.label | text | Text of the submit button. Default: "Send" for a new record, "Save" when editing (Italian: "Invia", "Salva"). | ||
[].submit.message | text | Message shown after saving. Default: "Saved — thank you." ("Salvato, grazie." in Italian). Not shown when redirect is set. | ||
[].submit.redirect | string | Key of a view to open after saving (/v/<key>). Must be a view of this app. | ||
[].export | boolean | false | type table, list or cards: adds a "Download CSV" link with the rows the user sees (same source, access rules and filters; at most 200 rows, whatever data.limit says). The CSV is UTF-8 with BOM; cells that a spreadsheet would run as a formula are defused. No link when there are no rows or the rows are locked by preview. Default false. | |
[].resources | string | type booking: what is booked (professionals, rooms, tables), as collection:<name> of a collection everyone reads (ownedBy: app or shared). The user first picks a resource; each resource has its own slots, and a resource record's slots object overrides the view's rule. Records with active: false are left out; at most 100 are listed. | ||
[].slots | object | type booking: the opening rule. Free slots are computed for the coming aheadDays, minus the slots already booked to capacity. A resource record's slots field overrides any of these keys for that resource. | ||
[].slots.days | list of integer | Days of the week open for booking: 1 = Monday … 7 = Sunday. Default Monday to Friday (1–5). | ||
[].slots.from | string | "09:00" | Opening time, HH:MM in tz. Default 09:00. Must be before to. Values: pattern ^\d{2}:\d{2}$. | |
[].slots.to | string | "18:00" | Closing time, HH:MM in tz. Default 18:00. The last slot ends at or before this time. Values: pattern ^\d{2}:\d{2}$. | |
[].slots.minutes | integer | 30 | Length of each slot in minutes, 5–480. Default 30. Slots start at from and follow each other without gaps. Values: ≥ 5; ≤ 480. | |
[].slots.tz | string | "Europe/Rome" | IANA time zone of the opening hours (e.g. Europe/London). Default Europe/Rome. | |
[].slots.aheadDays | integer | 14 | How many days ahead, from today, slots are offered (1–120). Default 14. Values: ≥ 1; ≤ 120. | |
[].slots.minNoticeHours | number | 2 | Minimum hours between now and a slot's start for it to be bookable (decimals allowed). Default 2. Values: ≥ 0. | |
[].slots.capacity | integer | 1 | Bookings allowed for the same slot (and resource), e.g. seats in a class (1–100). Default 1. Values: ≥ 1; ≤ 100. | |
[].map | object | type map: markers from the view's source rows, read with the same access rules as a table (at most 200 rows; rows without valid coordinates are skipped). Filters, sort and path come from data. | ||
[].map.lat | string | "lat" | Field with the latitude (a number, or text with a dot or comma decimal). Default lat. | |
[].map.lon | string | "lon" | Field with the longitude. Default lon. | |
[].map.title | string | "name" | Field shown in bold in each marker's popup. Default name. | |
[].map.popup | list of string | Fields whose values are shown under the title in the popup, one per line (at most 6; empty values left out). Values: max items 6. | ||
[].map.tiles | string | Tile URL template, https with a {z} placeholder (e.g. https://…/{z}/{x}/{y}.png). Default OpenStreetMap, meant for light use only: a busy app should use its own tile provider. Values: pattern ^https://\S+\{z\}\S*$. | ||
[].map.attribution | string | Attribution shown on the map (at most 200 characters). Default "© OpenStreetMap contributors"; set it when you use other tiles. Values: max length 200. |
spec.schedules
list of object. Timers of the app. Schedules with owner app run in the runtime's scheduler tick; each fires at most once per tick, and after an outage the tick catches up at most the last 3 hours.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].agent | string | Key of the agent to start (with action run or digest). Its goal is goal, else the agent's goalTemplate, else Run your scheduled task for {date}.; its startOptions apply. When it finishes, the answer becomes a record of the agent's writesTo collection and is emailed if deliver is set. Runs not finished after 6 hours are marked failed. | ||
[].job | string | Key of a data job in spec.data.jobs to execute (with action run or ingest). The job must be linked (published); otherwise the tick logs not linked. Used only when agent is not set. | ||
[].action | enum | "run" | What the schedule does. run (default): start the agent, or the job. digest: same as run for an agent. ingest: same as run for a job. settle: check up to 50 running or unsettled form runs and settle their credits. sync: not run by the runtime yet. Values: run, sync, settle, ingest, digest. | |
[].cron | string | yes | When it fires: a standard 5-field cron (minute hour day-of-month month day-of-week) in UTC, with *, lists, ranges and steps; Sunday is 0 or 7. | |
[].owner | enum | "app" | app (default): the runtime's scheduler runs it. platform: a platform trigger (scheduled agent or job cron); the runtime skips it. Values: platform, app. | |
[].goal | string | The task for the agent on each run. Placeholders: {date} (UTC, YYYY-MM-DD), {lang} (the app's default language), {role} (scheduler); {user} is empty. Default: the agent's goalTemplate, else Run your scheduled task for {date}. | ||
[].deliver | deliver | Emails the report of each finished run. A schedule needs an agent and an explicit to (admins or role:<key>): an app-wide schedule has no owner. |
spec.billing
object. How end users pay. Packs and plans are paid through Stripe Checkout to the app owner's connected account, with the platform keeping an application fee; credits are spent on runs and chat messages. Platform usage (LLM, compute) is metered to the owner's organisation separately. Admins never pay.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
modes | list of enum | yes | The ways users pay (at least one, no repeats). Validation enforces: free cannot be combined with other modes; credits needs packs, plans with credits or signupCredits; subscription needs plans. The runtime charges whatever costs says whatever the mode; per_transaction is accepted but payments between users are not available yet. Values: min items 1; free, credits, subscription, per_transaction. | |
currency | string | "eur" | Currency of the prices of packs and plans, as an ISO code (default eur). Used for Stripe Checkout and to format prices and money values on pages. | |
platformFeePct | number | Meant as the platform's fee percentage. Not used by the runtime: the application fee on payments is set by the platform (10% unless configured otherwise), never by the manifest. Values: ≥ 0; ≤ 100. | ||
signupCredits | integer | Credits a new user gets once, when they first sign in. Values: ≥ 0. | ||
metering | object | Settings for costs marked metered: credits are held on the estimate when a form run starts and settled on the run's measured usage when it ends (fully refunded when the run produces no report). If the platform recorded no tokens, the estimate is charged. | ||
metering.creditEur | number | Value of one credit in euros (default 0.01). Credits charged = the price in euros divided by this value, rounded up. | ||
metering.markupPct | number | Percentage added to the measured cost to get the price (default 50). Values: ≥ 0. | ||
metering.drivers | list of enum | Which measured costs are priced (default llm_tokens and compute). llm_tokens: the run's tokens at the model's rate; compute or vm: whole VM-hours of the run's duration (at least one). browser, proxy and storage are accepted but not priced by the runtime yet. Values: llm_tokens, compute, browser, proxy, storage, vm. | ||
metering.allowNegative | boolean | When the measured price is above the held estimate and the user's balance cannot cover the difference: true takes it anyway and the balance goes below zero; otherwise (default) the runtime takes what the balance has and records the rest as unpaid. | ||
costs | map of number | object | What actions cost, in credits, by key. agent:<key> prices a form run of that agent and each chat message to it; run is the fallback price of any form run whose agent has no entry. Other keys are accepted but not charged. The credits are held when the run starts (a run fails with 402 when the balance is too low) and returned if it produces no report; admins run for free. | ||
packs | list of object | One-off purchases that add credits. They are listed with a Buy button on the account view; payment goes through Stripe Checkout and the credits are added once, when the payment completes. A completed purchase also fires triggers with on.payment set to the pack key (or *). | ||
packs[].key | key | yes | Identifier of the pack (lowercase letters, digits, _ and -), used by checkout and by on.payment triggers. Validation also accepts it where a plan key is expected, but buying a pack does not give the user that key as a plan. | |
packs[].credits | integer | Credits added to the buyer's balance when the payment completes (none if 0 or missing). Values: ≥ 0. | ||
packs[].price | number | yes | Price in units of billing.currency (e.g. 9.9 = 9.90 EUR), charged once. Values: ≥ 0. | |
packs[].label | text | Name of the pack shown on the account view and in Checkout (defaults to key). | ||
packs[].unlocks | list of string | Option values or views a pack is meant to unlock. Accepted by the schema; not used by the runtime yet. | ||
plans | list of object | Subscriptions. They are listed with a Subscribe button on the account view; while a subscription is active the user holds the plan's key, which unlocks what gatedBy, requiresPlan, preview.unlessPlan and per-plan limits name. The key is removed when the subscription ends. | ||
plans[].key | key | yes | Identifier of the plan (lowercase letters, digits, _ and -), stored on the subscribed user and named by gatedBy, requiresPlan, unlessPlan, limits' plans and on.payment triggers. | |
plans[].price | number | yes | Price per interval in units of billing.currency. Values: ≥ 0. | |
plans[].interval | enum | yes | How often the subscription is billed: month or year. Values: month, year. | |
plans[].label | text | Name of the plan shown on the account view and in Checkout (defaults to key). | ||
plans[].includes | list of string | What the plan includes. Accepted by the schema; not used by the runtime yet (not shown on the account view). | ||
plans[].credits | integer | Credits added to the subscriber's balance on each paid invoice (each billing period). Unspent credits are kept. Values: ≥ 0. | ||
plans[].creditsReset | enum | monthly: the plan's credits meant as an allowance spent before purchased packs; never: they accumulate. Accepted by the schema; not used by the runtime yet: each paid invoice adds the credits to the same balance. Values: monthly, never. | ||
plans[].transactionFeePct | number | per_transaction: the fee on payments between users for subscribers of this plan. Accepted by the schema; not used by the runtime yet. Values: ≥ 0; ≤ 100. | ||
plans[].roles | list of key | Roles meant to be allowed to buy the plan. Accepted by the schema; not used by the runtime yet: every signed-in user can subscribe. | ||
transactionFeePct | number | per_transaction: the owner's fee on each payment between users (the default when a plan sets none). Accepted by the schema; not used by the runtime yet. Values: ≥ 0; ≤ 100. | ||
sellers | string | per_transaction: collection:<name> whose records would be paid through their own connected accounts. Validation checks that the collection is declared; not used by the runtime yet. | ||
revenueShare | list of object | Payouts to third parties. Accepted by the schema; not used by the runtime yet (validation checks that to names a declared collection). | ||
revenueShare[].to | string | yes | collection:<name>: the records that would be paid. Validation checks that the collection is declared; not used by the runtime yet. | |
revenueShare[].pct | number | yes | Percentage (0 to 100) of basis that would be paid out. Not used by the runtime yet. Values: ≥ 0; ≤ 100. | |
revenueShare[].basis | string | yes | What the percentage would apply to, in words (e.g. paid credits whose content the agent used). Not used by the runtime yet. | |
revenueShare[].payout | enum | "manual" | How payees would be paid: manual (default) by the owner, connect through their own Stripe connected accounts. Not used by the runtime yet. Values: manual, connect. |
spec.notifications
object. Emails about runs. emailOnRunDone: email users when their form run ends. For periodic reports use schedules[].deliver or templates[].deliver.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
emailOnRunDone | boolean | Email the user when their form run ends: the report's title and link (/r/<run id>), or a note that the request did not complete and no credits were charged. The same message goes to their phone when the app has push. With it on, the scheduler tick also checks up to 50 running runs each time, so the email leaves even when nobody watches the page. | ||
digest | string | Cron of a periodic email digest. Accepted by the schema; not used by the runtime yet: use schedules[].deliver or templates[].deliver. |
spec.exports
list of object. Endpoints the app would serve to other programs. Accepted by the schema; not used by the runtime yet. To let users download data, set export: true on a table, list or cards view: it serves the rows that user can see as CSV.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].path | string | yes | URL path of the endpoint, starting with /api/. Not used by the runtime yet. Values: pattern ^/api/. | |
[].source | string | yes | Data the endpoint would serve. Not used by the runtime yet. | |
[].format | enum | "json" | Output format: json (default), csv, xml or rss. Not used by the runtime yet. Values: json, csv, xml, rss. | |
[].access | enum | "user" | Who could call it: user (default), public, signed_url or token. Not used by the runtime yet. Values: public, signed_url, token, user. |
spec.mobile
object. The phone app: one Capacitor shell, generated from the manifest, that opens this app's web address (host, else <slug>.webrobot.eu), so screens, agents and data are the same as on the web and go through the person's own session. Only the phone capabilities listed here are installed. It is exported as a project with build workflows for Android and iOS; sign-in on the phone uses the 6-digit code from the email.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
appId | string | yes | Store identifier in reverse-DNS form, lower case, at least three parts, e.g. com.example.myapp. It becomes the Android package name and the iOS bundle id, and cannot change once the app is in a store. Values: pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,}$. | |
appName | string | Name under the icon on the phone (at most 30 characters). Default: displayName. Values: max length 30. | ||
version | string | Version shown in the stores, x.y.z. Default 1.0.0. Values: pattern ^\d+\.\d+\.\d+$. | ||
build | integer | Build number (at least 1), default 1. The build workflows add the CI run number to it, so every store upload gets a higher one. Values: ≥ 1. | ||
orientation | enum | "portrait" | Screen orientation: portrait (default) locks the app to portrait; any follows the phone's rotation. Values: portrait, any. | |
capabilities | list of object | Phone features the app uses (at most 15, each once). Only their plugins and permissions go into the shell. Each one must be used by something in the app (e.g. location by a location field, barcode by a barcode field, camera by a file field with capture, biometrics by lock), except files, haptics and share; in turn a location, barcode or photo field, a share or calendar action and lock each need their capability declared. These checks run when the app is designed and when the phone app is exported.contacts, bluetooth, backgroundLocation, localNotifications and speech cannot be used by any part of an app yet. Values: max items 15. | ||
capabilities[].name | enum | yes | The capability: camera, location, backgroundLocation (needs location too), push, localNotifications, biometrics, contacts, calendar, microphone, speech, bluetooth, barcode (raises the minimum Android version to 8), files, share, haptics. Values: camera, location, backgroundLocation, push, localNotifications, biometrics, contacts, calendar, microphone, speech, bluetooth, barcode, files, share, haptics. | |
capabilities[].reason | text | Why the app needs the capability; the phone shows it when it asks for the permission (on iOS it becomes the usage description). Required for camera, location, backgroundLocation, biometrics, contacts, calendar, microphone, speech, bluetooth and barcode; written in defaultLang. | ||
allowNavigation | list of string | Other hosts the shell may open inside the app instead of the browser. The app's own host and Stripe Checkout are always allowed. | ||
lock | "biometric" | biometric: when someone is signed in, the phone app opens (and returns from the background) only after Face ID, fingerprint or the phone's code. Requires the biometrics capability. Without biometrics set up on the phone, there is no lock. |
spec.extensions
list of object. Documents custom logic the manifest cannot express yet. Informational only: the runtime serves nothing from it, and app tools marked with an extension are not served.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Identifier of the extension. | |
[].description | string | yes | What the custom logic does. | |
[].where | string | Where the code of the hand-built app that holds this logic is. Informational only. |
spec.header
object. The top bar for visitors: links to sections of the home page, a call-to-action button and an announcement strip.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
links | list of object | Links in the header (at most 8). Shown to visitors who are not signed in, and to signed-in users who have no menu pages; otherwise the header shows the app's pages. Values: max items 8. | ||
links[].label | text | yes | Text of the link. | |
links[].href | string | yes | Target: a path of this app (/…), an anchor on the page (#…) or an https:// URL. Values: pattern ^(/(?!/)|#|https://). | |
cta | object | Call-to-action button shown to visitors who are not signed in, in place of the Sign in button. | ||
cta.label | text | yes | Text of the button. | |
cta.href | string | yes | Target: a path of this app (/…, e.g. /login), an anchor (#…) or an https:// URL. Values: pattern ^(/(?!/)|#|https://). | |
announcement | text | One line shown above the header on every page, to everyone. Markdown; links allowed. |
spec.slots
list of object. The app's own Python functions (at most 20), run in a sandbox (WebAssembly, no network, no files, no environment, 128 MB of memory). An agent context entry from: slot:<key> runs one when a form run starts, and an app tool with action call runs one when the agent calls it. Values: max items 20.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique key of the slot, referenced by context[].from: slot:<key> and appTools[].slot. | |
[].description | string | What the slot computes, at most 300 characters. For people reading the manifest; the runtime does not use it. Values: max length 300. | ||
[].code | string | yes | Python 3.12 source, at most 64,000 characters. Define main(input) returning JSON-serialisable data, or print one JSON value; at most 256 KB of output. Input: {values, lang} when run for an agent's context, {args, userId} when run as a tool. A slot that fails stops the form run before any credit is held. Values: max length 64000. | |
[].timeoutMs | integer | 3000 | Wall-clock limit of one call, in milliseconds: 100 to 10,000, default 3000. Values: ≥ 100; ≤ 10000. | |
[].example | An example input, used by the App Studio's slot test. The runtime does not use it. |
spec.serviceHours
object. When the app's agent must answer fast. During these hours the organization's dedicated chat host is kept on and chat messages are answered there, in the same request; outside them, or when the host is not ready, each chat message is one agent run. The scheduler tick turns the host on leadMinutes before opening and off after closing.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
timezone | string | IANA time zone of the slots, e.g. Europe/Rome. Default: metadata.timezone, else Europe/Rome. | ||
leadMinutes | integer | 10 | Minutes before each opening when the host is started, so it is ready on time: 0 to 60, default 10. Values: ≥ 0; ≤ 60. | |
slots | list of object | yes | Opening periods, 1 to 14. The app is in service when any slot covers the current local time. Values: min items 1; max items 14. | |
slots[].days | list of integer | yes | Weekdays the slot applies to: 1 = Monday … 7 = Sunday. For a slot that passes midnight, the day is the one it starts on. Values: min items 1. | |
slots[].from | string | yes | Opening time, HH:MM (24-hour, local), included. Values: pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$. | |
slots[].to | string | yes | Closing time, HH:MM (24-hour, local), excluded. A time earlier than from means the slot ends the next day. Values: pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$. |
spec.teams
list of object. Agents working together, published as ONE agentic profile named <slug>-team-<key>: sequence runs steps whose outputs flow to the next (a DAG); swarm is a lead and members on a shared task board. A team is started by a trigger (start.team) or a template (team).
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique key of the team, referenced by triggers[].start.team and templates[].team. It may not equal an agent's key. | |
[].description | string | What the team does. Publishing uses it as the profile description (default <displayName> — team <key>). | ||
[].title | text | Display title of the team. Accepted by the schema; not used by the runtime yet. | ||
[].mode | enum | yes | sequence: steps run in order (or after the steps named in after) and must form a DAG. swarm: lead plans and closes the work, members work on a shared board. Values: sequence, swarm. | |
[].steps | list of object | mode sequence: the steps, at least one. Each step runs after the previous one, or after the steps listed in its after. An agent may appear only once, and cycles are refused. | ||
[].steps[].agent | string | yes | Key of the agent that runs this step (it must be inline). | |
[].steps[].after | list of string | The steps (agent keys) this one waits for. Default: the previous step; the first step has none. | ||
[].lead | string | mode swarm: the agent that plans and closes the work (required for a swarm). | ||
[].members | list of string | mode swarm: the agents on the board (at least one). | ||
[].maxMinutes | integer | Time limit of a swarm, in minutes (1–180), passed to the swarm as its maximum duration. Ignored for sequence teams. Values: ≥ 1; ≤ 180. | ||
[].goalTemplate | string | The team's task for a template instance when the template has no goal; same placeholders as the template goal. A trigger that starts the team uses the trigger's goal (or a default), not this. | ||
[].writesTo | object | As for an agent: the result of each triggered or template-instance run of the team becomes a record of collection (with parse and keyBy). | ||
[].profile | object | Set by publishing: the profile compiled from the team. Do not write it by hand. | ||
[].profile.ref | integer | string | Id of the team's published profile; the runtime starts the team through it. A team without it is not published. |
spec.triggers
list of object. Events that do something without a person: start an agent, a team or a data job, send an email, save a record, or charge credits. An app cannot start more than 20 triggered actions a minute (further ones are skipped), and spec.limits with action agents or agent:<key> caps the agents its events start.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique key of the trigger. A webhook trigger is called at POST /api/hooks/<key>. | |
[].description | string | What the trigger is for. For people reading the manifest; the runtime does not use it. | ||
[].on | object | yes | The event source: exactly one of cron, collection, webhook, payment, approval, call, date. op and where refine collection (where also call and date), decision refines approval, callEvent refines call. | |
[].on.cron | string | A 5-field cron in UTC, checked by the scheduler tick (at most once per tick, catching up at most 3 hours). A timed trigger has no user and no record: only start and notify are run, and the goal is goal or Run your scheduled task for {date}. (the agent's goalTemplate is not used). | ||
[].on.collection | string | A declared collection: fires when one of its records is written by a form, a booking, the admins' data page, an app tool, an agent's writesTo or another trigger's write. | ||
[].on.op | enum | "insert" | Which writes of collection fire it: insert (default) for a new record, update for a change to an existing one, any for both. Values: insert, update, any. | |
[].on.where | object | Fields the record must have, compared as text for equality, e.g. {status: confirmed}. Applies to collection, date and call events. A record created without the field gets the collection's field default first, so where on a default value matches. | ||
[].on.webhook | boolean | true: the trigger is called at POST /api/hooks/<key> with the header X-Hook-Secret (the app's hook secret). Optionally the sender signs with X-Hook-Timestamp (unix seconds, within 5 minutes) and X-Hook-Signature (hex HMAC-SHA256 of <timestamp>.<body>). The body (at most 64,000 characters, JSON or text) is the event; the answer is 202. | ||
[].on.payment | string | A plan or pack key, or * for any purchase: fires once per completed purchase, for the user who paid. | ||
[].on.approval | string | Key of an approval: fires when a request of that approval is decided (by a person or at its timeout). The record holds the request's fields plus approvalId, summary and note. | ||
[].on.decision | enum | "any" | Which decisions fire it: approved, rejected or any (default). A request that times out is delivered as approved or rejected according to the approval's onTimeout, so timeout never matches today. Values: approved, rejected, timeout, any. | |
[].on.call | string | Key of a phone channel (or phone when the channel has no key): the call's moments, with caller, transcript, duration and outcome in the record. Validated against spec.channels; the runtime does not receive calls yet, so it does not fire today. | ||
[].on.callEvent | enum | "ended" | Which moment of a call fires it: started, ended (default) or missed. Only with call. Values: started, ended, missed. | |
[].on.date | object | Reminders: fires for each record of collection whose date field, moved by offsetDays, is today (UTC). Checked by the scheduler tick from hour on, once per record and date, at most 200 records per tick; where filters the records. | ||
[].on.date.collection | string | yes | The declared collection whose records are checked. | |
[].on.date.field | string | yes | A date (YYYY-MM-DD, read as midnight UTC) or date-time field of the record. Records with an empty or invalid value are skipped. | |
[].on.date.offsetDays | integer | 0 | Days added to the date before comparing with today: -1 = the day before the date, 3 = three days after. -365 to 365, default 0. Values: ≥ -365; ≤ 365. | |
[].on.date.hour | integer | 7 | Hour of the day (UTC, 0–23) from which the day's reminders are sent; default 7. Values: ≥ 0; ≤ 23. | |
[].start | object | Start exactly one of an agent, a team or a data job. Agent and team runs are recorded and collected by the scheduler tick; their result goes to the agent's or team's writesTo collection. | ||
[].start.agent | string | Key of the agent to start (it must be published). It gets the event's user's app session (with asUser) and its memory of that user. | ||
[].start.team | string | Key of the team to start (it must be published). | ||
[].start.job | string | Key of a linked data job in spec.data.jobs to execute. | ||
[].goal | string | The task for a started agent or team. {event} is the event as JSON (at most 8000 characters), {record.<field>} or {<field>} a field of the record, {date} today (UTC). Default: the started agent's goalTemplate, else An event happened in the app: {event}. Do your task for it. When the goal does not mention {event}, {id} or {record.id}, the record's collection and id are appended. | ||
[].asUser | boolean | true | true (default): act for the user the event belongs to (the record's user, the buyer, the requester): the agent gets their app session, so its tools reach only their records, and notify to owner and charge use them. false: no user. | |
[].notify | notify | Send a plain-text email instead of starting an agent (see $defs/notify). | ||
[].write | object | Save the event's data as a record, without an agent (a webhook from a device, a partner, an external form). A cron trigger does not run it (a timed event carries no data). The target may not be owned by instance nor be the collection that fires the trigger; a user-owned target needs the event's user. Saving the record fires that collection's triggers in turn. | ||
[].write.collection | string | yes | The declared collection the record is written to. | |
[].write.fields | map of string | Mapping record field → dot path in the event's data (e.g. temperature: reading.temp). Default: the event's top-level values whose names are fields declared by the collection. Objects are stored as JSON text (at most 4000 characters); the whole record may be at most 32,000 characters. | ||
[].write.keyBy | string | A mapped field whose value becomes the record id, so the same event delivered twice updates one record instead of creating two. Without it every event creates a new record. | ||
[].charge | object | Take credits from the event's user, once per event (a success fee when a case is approved, a fee per contact). The balance may go below zero. Needs an event with a user: not with cron or webhook. | ||
[].charge.credits | integer | yes | Credits taken, 1 to 100,000. Values: ≥ 1; ≤ 100000. | |
[].charge.reason | string | Text of the ledger entry the user sees, at most 120 characters. Default: the trigger's key. Values: max length 120. |
spec.approvals
list of object. Human checkpoints: an agent that awaits the approval asks with the tool request_<key>, a person decides in an approvals view, and triggers on the approval resume the work.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique key of the approval, referenced by agents[].awaits, triggers[].on.approval and views[].approvals; the generated tool is request_<key> (hyphens become underscores). | |
[].title | text | Label of the request shown in the approvals view. Default: the key. | ||
[].description | string | What is being approved; it goes into the description of the request_<key> tool the agent sees. | ||
[].role | string | The role that decides (a key of auth.roles): a staff role (admin, invite or derived), never the signup role. The app's admins can always decide; nobody decides their own request. Required unless decidedBy is requester, which takes no role. | ||
[].fields | list of string | Fields of the request shown to the person who decides. Default: every field of the request. | ||
[].timeoutMinutes | integer | Minutes after which a pending request is decided by onTimeout (checked by the scheduler tick): 1 to 10,080 (7 days). Without it a request waits until someone decides. Values: ≥ 1; ≤ 10080. | ||
[].onTimeout | enum | "reject" | The decision at the timeout: reject (default) or approve. The decision is recorded as approved or rejected, decided by timeout. Values: approve, reject. | |
[].decidedBy | enum | "role" | role (default): people with role (or the app's admins) decide, never on their own request. requester: only the user whose agent asked confirms it (their own agent's proposal: a shortlist, a weekly plan); the request needs that user's session. Values: role, requester. |
spec.templates
list of object. Agents the app's users create for themselves (an instances view lists them): each instance has its own parameters, schedule, memory and records. A run of an instance starts like a triggered run and its result becomes a record of the agent's (or team's) writesTo collection, stamped with the instance.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | yes | Unique key of the template, referenced by an instances view (template). | |
[].title | text | Heading of the instances view for this template. Default: the key. | ||
[].description | text | Text shown under the heading of the instances view. | ||
[].agent | string | Key of the agent each instance runs. Exactly one of agent and team. | ||
[].team | string | Key of the team each instance runs. Exactly one of agent and team. | ||
[].params | list of field | yes | The parameters a user fills in when creating an instance (form fields; names must be unique). Values are checked: required, numbers, booleans, url (an http(s) address), options; text is cut at maxLength, default 2000 characters. A field fed by optionsFrom: collection:<name> must name a record the user may read. | |
[].schedule | object | When instances run on their own. Without a cron an instance runs only when its owner presses Run. | ||
[].schedule.cron | string | Default 5-field UTC cron of a new instance. A cron given by the user may contain only digits, spaces and * , / -. | ||
[].schedule.userCanChange | boolean | true | true (default): the user may set their own cron when creating or editing an instance. false: every instance uses cron. | |
[].maxPerUser | integer | 5 | How many instances (active or paused) one user may have: 1 to 1000, default 5. Values: ≥ 1; ≤ 1000. | |
[].roles | list of string | Roles allowed to create instances. Default: everyone signed in; the app's admins always can. | ||
[].cost | object | Credits charged to the user who owns the instance. | ||
[].cost.perRun | number | Credits taken (rounded to a whole number) when each run starts; the run does not start without them. Returned if the start fails or the run ends without a result. Runs an admin starts by hand are free. Values: ≥ 0. | ||
[].cost.perMonth | number | Monthly credits per instance. Accepted by the schema; not used by the runtime yet. Values: ≥ 0. | ||
[].goal | string | The task of each run: the params as {name}, {instance} (the instance's title), {date} (UTC), {lang} (the app's default language), {user} (the owner's email). Default: the agent's (or team's) goalTemplate, else one name: value line per filled param. | ||
[].deliver | deliver | Emails the report of each finished instance run; to defaults to owner, the instance's owner. |
spec.channels
list of object. Where conversations reach an agent: web is the app's chat views; phone, telegram and email connect an agent to a number, a bot, a mailbox. Only validated today (the agent must exist; triggers[].on.call must name a phone channel): the runtime does not connect any channel yet, and chat views choose their agent with source.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
[].key | key | Key of the channel, referenced by triggers[].on.call. Default: the channel's type. | ||
[].type | enum | yes | web (the app's chat views), phone, telegram or email. Values: web, phone, telegram, email. | |
[].agent | string | yes | Key of the agent that answers on this channel (must exist). | |
[].greeting | text | First message to the caller or visitor. Accepted by the schema; not used by the runtime yet. | ||
[].language | string | Language of the conversation. Accepted by the schema; not used by the runtime yet. | ||
[].voice | string | Voice of a phone channel. Accepted by the schema; not used by the runtime yet. | ||
[].number | string | phone: the number, set when the phone is activated. Accepted by the schema; not used by the runtime yet. | ||
[].address | string | email: the inbox address. Accepted by the schema; not used by the runtime yet. |
spec.egress
object. The external hosts the app's http tools may call (public HTTPS APIs whose terms allow it). Nothing else is reachable: every http tool's URL host must be listed here or validation fails, and at call time the runtime also refuses any host that resolves to a private or internal address and does not follow redirects.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
hosts | list of string | yes | Allowed hosts (at most 20), exact names such as api.example.com. A *.<domain> entry is only for the user's own host saved with their credential (a tool URL starting with https://{host}, e.g. *.myshopify.com). Values: max items 20. | |
notes | string | Why each host is used and its terms of use or licence (at most 1000 characters). For reviewers; not used by the runtime. Values: max length 1000. |
Shared types
Types used in several places, linked from the tables above.
lang
string. A two-letter lower-case language code, e.g. en. Values: pattern ^[a-z]{2}$.
key
string. An identifier: starts with a lower-case letter, then lower-case letters, digits, _ or -. Values: pattern ^[a-z][a-z0-9_-]*$.
color
string. A colour as #rrggbb (six hexadecimal digits). Values: pattern ^#[0-9a-fA-F]{6}$.
palette
object. A set of the four main colours. Each becomes a CSS variable (--primary, …); a colour left out keeps the runtime default.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
primary | color | Headings, the app name in the header, the announcement strip and numbered markers. Default #1f2a44. | ||
accent | color | Links, main buttons (unless branding.button names another colour), highlights and chart series. Default #2563eb. | ||
background | color | Page background; cards and lines are derived from it. Default #f7f8fa. | ||
foreground | color | Body text colour. Default #161b26. |
text
string | object. A text shown to people: a plain string, or one string per language (e.g. {en: Book, it: Prenota}). The runtime shows the visitor's language; if that one is missing, the first string given.
option
string | object. A choice of a select or multiselect field: a plain string (value and label are the same) or an object with its own label, a plan gate and a parent.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
value | string | yes | The value stored and passed to the agent. | |
label | text | What the person sees; default: the value. In a run form the chosen label is also available to the goal as {<field>_label}. | ||
gatedBy | string | Key of a plan or pack that unlocks this option. Users without it see the option disabled, with the plan it needs; app admins are exempt. The server enforces it on the run form (HTTP 402); collection forms only disable it in the page. | ||
parent | string | With dependsOn on the field: the value of the parent field this option belongs to. The form shows only the options of the chosen parent; the server enforces it on the run form. |
field
object. A field of a form: the input form of runs (spec.inputForm.fields), a collection's records (data.collections[].fields, shown by form views and the admins' data page), or a template's parameters. The server checks every submitted value again; the browser form is only a convenience.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
name | string | yes | Key of the value (lowercase letters, digits and _, starting with a letter). In an input form it is also the goal placeholder {name}; for a select, {name_label} gives the chosen option's label, and for a file field {name_text} gives the extracted text. Values: pattern ^[a-z][a-z0-9_]*$. | |
label | text | Text shown next to the input (defaults to name); also used in error messages and to match CSV column headers on the data page. | ||
type | enum | yes | The kind of input and how the value is checked and stored. text (single line), textarea (multi-line), email, url, date (date picker): text; record forms also check the email shape and a YYYY-MM-DD date. number: must be a number ("not a number" otherwise). boolean: a checkbox, stored as true/false. select: one value of options (or of the records named by optionsFrom); multiselect: a list of them. urls, array: a list, one value per line (or comma-separated). file: an upload (see accept, maxMb, multiple, extract, capture). location: a position stored as "lat,lng" with 6 decimals, from GPS on phones. barcode: a code read with the camera or typed (one line, at most 512 characters). country, city, object, json and relation are shown as a plain text input and stored as text (a field with optionsFrom becomes a select). Values: text, textarea, number, boolean, select, multiselect, url, urls, email, date, file, country, city, object, array, relation, json, location, barcode. | |
required | boolean | The field must have a value: the server answers "<label> is required". In the run form an unticked required boolean also counts as missing (use it for consent); in record forms booleans are never required. A required file field needs at least one uploaded file. | ||
maxLength | integer | Most characters for a text value. The input form refuses longer text ("at most N characters"); record forms cut it to this length (10,000 characters when not set); template parameters are cut to it (2,000 when not set). Values: ≥ 1. | ||
options | list of option | The choices of a select or multiselect: plain strings, or objects with value, label, gatedBy and parent. A value not in the list is refused ("invalid choice"). Data blocks show the option's label for a stored value. | ||
optionsFrom | string | collection:<name>[.<labelField>]: the choices are the records of that collection the user may read (newest first, up to 200), with the record id as value and labelField (or a usual name field) as label; the field is shown as a select (or stays a multiselect). The server refuses an id the user may not read. When nothing can be chosen yet, the form says so and links to a form view that adds one. job:<key> is not supported by the runtime. | ||
dependsOn | string | Name of another field of the same form whose value filters this field's options: only options whose parent equals that value (and options without a parent) are shown, and the choice is reset when the parent changes. The input form also refuses, on the server, an option that does not belong to the chosen parent. Validation checks that the field exists in inputForm. | ||
visibleWhen | string | Show the field only when the condition holds on the other values: field == 'x', field != 'x', field (has a value) or !field, joined with && and ||; anything else counts as false. In the input form, the value of a hidden field is dropped on the server. | ||
roles | list of string | Only users holding one of these roles see the field. In the input form the server ignores a value sent by other users and uses default instead; in record forms the field is only hidden in the page. | ||
default | The starting value in the form. In the input form an empty field takes it on the server (and users without the field's roles always get it). In a collection, new records that lack the field get it, whoever creates them (form, agent tool, trigger), so a trigger on e.g. status: pending fires for records made without that field. | |||
help | text | Hint shown in the input as its placeholder (under the field for template parameters); for a collection field, also the description of that field in the agents' write and append tools. | ||
gatedBy | string | Key of the plan that unlocks the whole field. In the input form, a user without the plan who fills the field gets 402 "<label> needs the plan <key>" (admins are exempt). Only subscription plans are recorded on users, so a pack key never unlocks it. Record forms do not check it. | ||
fields | list of field | type object or array: sub-fields. The runtime does not render or check them yet; they are only read to find the phone capabilities (camera, location, barcode) a phone app must ask for. | ||
relation | string | type relation: the target collection. Accepted by the schema; not used by the runtime yet: to pick a record, set optionsFrom: collection:<name>. | ||
accept | list of enum | type file: the file extensions accepted (at most 12). Default: pdf, docx, xlsx, csv, txt, jpg, jpeg, png, webp. The server also checks that the bytes match the extension and refuses others with "this field accepts …". Values: max items 12; pdf, docx, xlsx, csv, txt, md, json, html, xml, jpg, jpeg, png, webp, gif. | ||
maxMb | number | type file: the largest file in MB (default 10, never more than 15). Larger files are refused with "the file is larger than N MB". Values: ≥ 0.1; ≤ 15. | ||
multiple | boolean | false | type file: allow up to 10 files instead of one (default false). The value is then a list of file ids. | |
extract | enum | "text" | type file: text (default) extracts the text of PDF, Word, Excel, CSV and text files at upload (up to 60,000 characters per file), and an agent run's goal gets it as {<field>_text} (all files of a run share 30,000 characters); none stores the file without text. Images have no text: an agent reads them with an app tool of action read_file. Values: text, none. | |
capture | boolean | type file: take a photo with the camera instead of choosing a file: images only, made smaller before upload, the native camera inside the phone app. A phone app built from the manifest then asks for the camera permission. |
appTool
object. A tool the app gives one agent over its MCP endpoint. The runtime runs it, never the agent: generic read/search/show/write/append over a declared collection, call of a Python slot, read_file of an uploaded file, http to an allowed external API. A tool over a collection owned by user or instance (and any tool with scope user or session) takes the app session from the agent's task, and reaches only that user's records plus those the collection's access rules give their role.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
name | string | yes | Tool name the agent calls: lowercase letters, digits and _, starting with a letter. Unique per app unless two agents declare the same tool with the same action, target and limits. Values: pattern ^[a-z][a-z0-9_]*$. | |
description | string | yes | What the tool does, for the agent (it sees this in its tool list). Two agents may describe a shared tool in their own words. | |
action | enum | yes | read: one record by id, or without id the newest 50 the user may read. search/show (same behaviour): records matching where (equal fields) and text, newest first, limit 1–100, default 20. write: update a record by id (needs write access) or create one; append: create one; created records get the collection's field defaults, count against create:<collection> limits and fire triggers. call: run the Python slot. read_file: the text (or the image) of a file uploaded by the session's user. http: one request to an external HTTPS API (see http). delegate, approval, remember are generated from delegates, awaits and memory: do not declare them by hand. Values: read, search, write, append, show, call, delegate, approval, remember, http, read_file. | |
collection | string | The declared collection the tool reads or writes (not a reserved one); required for read, search, show, write, append. For an agent visitors use without signing in, a tool may not reach an org collection nor write an app or shared one. | ||
scope | string | user or session: the tool takes the app session and acts for that user. A tool over a collection owned by user or instance, read_file, and an http tool with a per-user credential take the session whatever this says. all and context:<key> are accepted by the schema; the runtime gives them no special meaning yet. | ||
extension | string | Key of an extension of the original app that implements the tool. Such tools are not served by the runtime and validation skips them, until they become a slot or an MCP server. | ||
slot | string | action call: key of the Python slot that implements the tool. The slot receives {args, userId} (args from the agent) and its return value goes back to the agent. | ||
agent | string | The delegated agent of a generated delegate tool (ask_<agent>). Set by the runtime from delegates; declare delegates instead. | ||
approval | string | The approval of a generated approval tool (request_<approval>). Set by the runtime from awaits; declare awaits instead. | ||
http | object | action http: the request the runtime makes. The agent fills only query (text, numbers, booleans), path (appended to url, when allowPath) and body (JSON, at most 100,000 characters; not for GET or DELETE); never headers, host, method or credentials. Only https, no redirects followed, addresses checked at connect time (no private or loopback networks). The answer is {status, data} for JSON, else {status, text} (at most 20,000 characters, with truncated), plus source when attribution is set. | ||
http.method | enum | "GET" | HTTP method: GET (default), POST, PUT, PATCH or DELETE. An agent visitors use without signing in may only have GET tools. The schema intends PUT, PATCH and DELETE for writing to the user's own account with a credential; the runtime does not enforce that. Values: GET, POST, PUT, PATCH, DELETE. | |
http.url | string | yes | Base URL, https:// only. Its host must be listed in spec.egress.hosts. https://{host}/… is the user's own host saved with their credential (their shop): it needs credential and a *.<domain> entry in spec.egress.hosts that the saved host matches. Values: pattern ^https://([A-Za-z0-9.-]+|\{host\})(/[^\s?#]*)?$. | |
http.allowPath | boolean | false | Let the agent append a path below url (e.g. /company/{number}): letters, digits, . _ ~ - /, at most 300 characters, no . or .. segments. Default false: a path is refused. | |
http.headers | map of string | Fixed, non-secret headers (e.g. Accept). Headers named Authorization, Cookie, X-Api-Key, Host, X-Forwarded*, Forwarded or Proxy-* are dropped; a key goes in credential. | ||
http.timeoutMs | integer | 20000 | Request timeout in milliseconds: 1000 to 30,000, default 20,000. Values: ≥ 1000; ≤ 30000. | |
http.maxBytes | integer | 500000 | Maximum response size in bytes: 1000 to 2,000,000, default 500,000. The response is cut beyond it and marked truncated. Values: ≥ 1000; ≤ 2000000. | |
http.attribution | string | Licence or attribution of the source, returned as source with every result (e.g. TED, CC BY 4.0). At most 200 characters. Values: max length 200. | ||
http.credential | object | A key connected for this provider (an api_key credential in spec.data.credentials: the session user's own, or the app's when its scope is org), added by the runtime; the agent never sees it, and it is masked as [credential] in the response. Default header: Authorization: Bearer {secret}. If the key is not connected, the tool answers 409 asking the user to connect it on their account page. | ||
http.credential.provider | string | yes | The provider of an api_key credential declared in spec.data.credentials. | |
http.credential.header | string | Header that carries the key, e.g. X-Shopify-Access-Token, X-API-Key. Default Authorization. Values: pattern ^[A-Za-z0-9-]{1,60}$. | ||
http.credential.format | string | How the header value is built around {secret}: Bearer {secret} (default), Token {secret}, {secret}. At most 60 characters. Values: max length 60. | ||
http.credential.query | string | Send the key as this query parameter instead of a header. Values: pattern ^[A-Za-z0-9_-]{1,40}$. |
section
object | object | object | object | object | object | object. One block of a page view, rendered top to bottom. The block type selects the form: hero, steps, cards, text, note, html, view or data. Text goes through the safe Markdown renderer; links may only be same-app paths, anchors or https.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
type | "hero" | yes | Block type; always hero for this kind of block. | |
id | string | Anchor of the block (lower case letters, digits and -, starting with a letter or digit), for links such as #how-it-works. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
eyebrow | text | Short line above the title (one line of Markdown). | ||
title | text | yes | The headline (one line of Markdown, required). Words in bold are shown highlighted. | |
text | text | Lead text under the title (Markdown). In a split hero without aside it fills the right column. | ||
actions | list of object | Buttons under the text, in order. A button to the sign-in page (/login…) is hidden for users who are already signed in. | ||
actions[].label | text | yes | Text of the button (plain string or one per language). | |
actions[].href | string | yes | Link: a same-app path (/v/…), an anchor (#…) or an https URL. Anything else becomes "#". Values: pattern ^(/(?!/)|#|https://). | |
actions[].style | enum | primary (default): a filled button; ghost: an outline button. Values: primary, ghost. | ||
note | text | Small line under the buttons, e.g. a trust line or what is included (one line of Markdown). | ||
layout | enum | stack (default): everything in one column. split: two columns, title and buttons on the left, aside (or the text) on the right. Setting aside also makes the hero split. Values: stack, split. | ||
aside | text | Right column of a split hero: an HTML card (e.g. an example conversation or a product mock), cleaned like an html block. Setting it makes the hero split. | ||
band | boolean | Shows the hero on a full-width tinted band. Default false. | ||
eyebrowStyle | enum | The line above the title: text (default) plain text, pill in a pill, pill-dot in a pill with a dot. Values: text, pill, pill-dot. | ||
type | enum | yes | steps: items numbered in order (how it works); cards: items without numbers (features, plans, use cases). Values: steps, cards. | |
id | string | Anchor of the block (lower case letters, digits and -, starting with a letter or digit), for links such as #how-it-works. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
title | text | Heading of the block (one line of Markdown). | ||
intro | text | Text under the heading, before the items (Markdown). | ||
items | list of object | yes | The items of the grid (at least one). Values: min items 1. | |
items[].title | text | Heading of the item (one line of Markdown). | ||
items[].text | text | Text of the item (Markdown). | ||
items[].badge | text | Shown above the item's title: an emoji alone is shown as an icon, any other text as a small badge. | ||
type | "text" | yes | Block type; always text for this kind of block. | |
id | string | Anchor of the block (lower case letters, digits and -, starting with a letter or digit), for links such as #how-it-works. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
title | text | Heading of the block (one line of Markdown). | ||
content | text | yes | Body of the block, in Markdown (required). | |
type | "note" | yes | Block type; always note for this kind of block. | |
id | string | Anchor of the block (lower case letters, digits and -, starting with a letter or digit), for links such as #how-it-works. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
content | text | yes | Text of the note, in Markdown (required). | |
type | "html" | yes | Block type; always html for this kind of block. | |
id | string | Anchor of the block (lower case letters, digits and -, starting with a letter or digit), for links such as #how-it-works. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
html | text | yes | Custom HTML (required; at most 100,000 characters are read). Only layout, text, table, image, link and details tags are kept; no script, form, iframe or style element. Attributes: class, id, href, src, alt, title, width, height, colspan, rowspan, open and style; href and src must be same-app paths, anchors or https. Inline style keeps only colour, background, font, spacing, border, size and flex/grid layout properties, never url() or imports. | |
type | "view" | yes | Block type; always view for this kind of block. | |
id | string | Anchor of the block (lower case letters, digits and -), for links such as #book. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
title | text | Heading shown above the embedded view. | ||
view | key | yes | Key of another view of this app (not the page itself). The block is left out when the visitor may not open that view, when it is a page, or, for visitors not signed in, when it is history, account, report or run. A report or run view shows the user's latest finished report with a link to it. | |
type | "data" | yes | Block type; always data for this kind of block. | |
id | string | Anchor of the block (lower case letters, digits and -, starting with a letter or digit), for links such as #how-it-works. Values: pattern ^[a-z0-9][a-z0-9-]*$. | ||
title | text | Heading of the block (plain text, Markdown is not rendered). | ||
intro | text | Text under the heading (plain text, Markdown is not rendered). | ||
source | string | yes | Where the rows come from (required). run: the signed-in user's runs (none for visitors); catalog[:<category>]: the platform's public source catalog, one category or a comma list (default all; cached 60 seconds); job:<key>: the latest dataset of a data job in data.jobs (cached 60 seconds; "Job not linked" when the job has no project and job id); collection:<name>: records of a declared collection the viewer may read (ownedBy: app or shared for everyone). Values: pattern ^(run|catalog(:[a-z_,]+)?|job:[a-z0-9_-]+|collection:[a-z0-9_]+)$. | |
path | string | Dot path (at most two levels) to a list inside each row; the lists of all rows are flattened into the rows shown (for example assets of each signal). Applied before filters. With a view source written collection:<name>.<path> the runtime fills this from the source when it is not set. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
display | enum | yes | How the rows are shown. Required. table (default rendering): one column per field; cards: a grid, first field as heading; list: one line per row, first field in bold; kpi: key numbers from kpis (shown even with no rows); bar: horizontal bars, first field = label, second = value; chart: an SVG chart of type chart. Values: table, cards, list, kpi, bar, chart. | |
fields | list of object | The columns, in order (at most 12). Without fields the runtime shows the first 6 field names found in the rows. On a collection: source (without path) a field with no label takes the collection field's label, and a select field shows the option label instead of the stored value. Values: max items 12. | ||
fields[].key | string | yes | Field of the row to show, as a dot path of at most two levels (e.g. price or address.city). For a job source it must be a dataset column. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | |
fields[].label | text | Column heading (plain string or one per language). Default: the collection field's label on a collection source, otherwise the key. | ||
fields[].format | enum | How the value is shown. text (default): as is; a value shaped like a position ("lat,lng") becomes a map link, an object is shown as JSON, and in a table a text longer than 220 characters shows a plain excerpt with the whole text on hover. number: locale number, at most 2 decimals; money: amount in the app's billing.currency (default EUR), no decimals; percent: the value is already a percentage, shown signed and coloured (+12.5%); ratio: a fraction multiplied by 100 and shown as a percent (0.25 → +25%); date: day, short month, year; link: an https URL as a clickable shortened link (other values as plain text); badge: a pill; location: a "lat,lng" position as a map link. An empty value shows a dash. Values: text, number, money, percent, ratio, date, link, badge, location. | ||
filters | list of object | Conditions every row must meet (all of them, at most 8), applied before grouping, sorting and the limit. On a job: source they become the WHERE clause of the dataset query. Values: max items 8. | ||
filters[].field | string | yes | Field the condition reads, as a dot path of at most two levels. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | |
filters[].op | enum | yes | Comparison. = and != compare as text; >, >=, <, <= compare as numbers and drop rows whose value is not a number; contains: case-insensitive substring match. Values: =, !=, >, >=, <, <=, contains. | |
filters[].value | string | number | boolean | yes | Value compared with the field: text, number or boolean. | |
sort | object | Order of the rows, applied after filters and grouping and before the limit. Without it rows keep the source order (a run source is newest first; grouped rows are ordered by group value, ascending). | ||
sort.field | string | yes | Field to order by (dot path of at most two levels). Numbers compare as numbers, anything else as text. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | |
sort.dir | enum | desc (default) or asc. Values: asc, desc. | ||
limit | integer | Maximum number of rows (or groups) shown, 1–200. Default 50. Key numbers (kpis) are computed on these rows only. Values: ≥ 1; ≤ 200. | ||
kpis | list of object | display kpi: the key numbers, at most 6, each an aggregate over the rows. Without kpis one number is shown: the row count. Values: max items 6. | ||
kpis[].label | text | yes | Text under the number (plain string or one per language). | |
kpis[].agg | enum | yes | The aggregate: count (rows, no field needed), sum, avg, min, max (over the field's numeric values; non-numbers ignored, empty when none), last (the field's value in the first non-empty row in the current order). Values: count, sum, avg, min, max, last. | |
kpis[].field | string | Field the aggregate reads (dot path of at most two levels). Not needed for count. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
kpis[].format | enum | How the aggregate is shown: number, money (app currency, default EUR), percent, ratio (×100 as a percent), date, link, badge or text. Default: number for count, plain value for the other aggregates. Values: text, number, money, percent, ratio, date, link, badge. | ||
empty | text | Message shown when there are no rows (not for display kpi). Default: "No data yet." ("Ancora nessun dato." in Italian). | ||
preview | object | Teaser for users without a plan: with unlessPlan set, users who do not hold that plan (admins excepted) see only the first rows rows, a line saying how many more rows the plan unlocks and no row buttons. | ||
preview.rows | integer | Rows shown to users without the plan. Default 3; 0 hides them all. Values: ≥ 0. | ||
preview.unlessPlan | string | Key of a plan or pack in billing; users whose plans include it see every row. Validation refuses a key that is not a plan or pack. | ||
chart | enum | display chart: the chart type. bar (default): grouped bars; line: lines with points; pie: one slice per row from the first series only (negative values count as 0); stacked: stacked bars (negative values ignored). The first field gives the labels, every other field a series. Values: bar, line, pie, stacked. | ||
groupBy | object | Groups the rows (after filters): one row per value of field (dates bucketed by day, week or month) with a count column and one column per aggregate in aggs; groups are ordered by value, ascending, then sort and limit apply. Use the group field, count and the agg keys as fields. minCount hides small groups; acrossUsers on a collection of user records aggregates every user's records anonymously (needs minCount ≥ 5; no record is ever shown). | ||
groupBy.field | string | yes | Field whose value forms the group (dot path). Rows with no value go to a group named "—". | |
groupBy.bucket | enum | Treats the field as a date and groups by day (YYYY-MM-DD), week (the date of that week's Monday) or month (YYYY-MM), in UTC. Rows whose value is not a date go to "—". Without bucket, every distinct value is a group. Values: day, week, month. | ||
groupBy.aggs | list of object | yes | The aggregate columns of each group (at most 8). count is always added. Values: max items 8. | |
groupBy.aggs[].key | string | yes | Name of the column the aggregate is written to; refer to it in fields, sort and kpis. Values: pattern ^[A-Za-z_][A-Za-z0-9_]*$. | |
groupBy.aggs[].agg | enum | yes | The aggregate over the group's rows: count (rows, no field needed), sum, avg, min, max (over the field's numeric values; non-numbers ignored, empty when none), last (the field's value in the first non-empty row in the current order). Values: count, sum, avg, min, max, last. | |
groupBy.aggs[].field | string | Field the aggregate reads (dot path). Not needed for count. | ||
groupBy.minCount | integer | Groups with fewer rows than this are left out (1–1000, default 1). Must be at least 5 with acrossUsers. Values: ≥ 1; ≤ 1000. | ||
groupBy.acrossUsers | boolean | On a collection: source whose collection is ownedBy: user: aggregates the records of every user, not only the viewer's, and shows only the groups (an anonymous benchmark). Validation refuses it on other sources and with minCount below 5; the runtime reads every user's records only when minCount is at least 5. | ||
actions | list of recordAction | Buttons on each row (at most 4): call, directions, share, add to calendar. Not shown on rows of a locked teaser. share and calendar add the matching permission to the phone app. Values: max items 4. |
notify
object. A plain-text email the app sends when the trigger fires (instead of starting an agent); the same message also goes to the recipients' phones when the app has push. subject and body may use {record.<field>} (or {<field>}), {date} (UTC) and {app} (the app's name), in the app's default language. Sent once per event; at most 300 emails per app per day and 10 per recipient per day, at most 50 recipients per email.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
channel | "email" | "email" | Delivery channel; only email (the default). | |
to | string | list of string | yes | Who receives it: owner (the user of the event or run), admins (the app's admin emails), role:<role key> (users holding that role; the admin emails for an admin role), record.<field> (an email address, or a list of them, in the record; only for events with a record: collection, date, approval, call or webhook). One value or a list of up to 5. | |
subject | text | yes | Subject line (text or one text per language); placeholders as in body. Cut at 200 characters. | |
body | text | yes | Body text (text or one text per language), with {record.<field>}, {<field>}, {date}, {app} and {?name}…{/name} blocks. A footer with the app's name and address is added; at most 20,000 characters. | |
link | string | A view key (becomes /v/<key>) or a path starting with /, appended to the body as a full link to the app (and opened by the push notification). |
deliver
object. Emails the report of each finished scheduled or template-instance run as plain text (Markdown kept, charts removed): to the instance's owner by default for a template, to admins or a role for a schedule. Subject to the same daily caps as notify.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
channel | "email" | "email" | Delivery channel; only email (the default). | |
to | string | list of string | Who receives it: owner (the instance's owner; the default), admins, role:<role key>. record.<field> is refused here (a report has no record). One value or a list of up to 5. | ||
subject | text | Subject line. Default: the report's title (its first # heading, else the app's name). {date} and {title} may be used. | ||
onlyIfNew | boolean | false | true: skip the email when the report is the same as the last one delivered for this schedule or instance. Default false. |
recordAction
object. A button shown on each record of a data list (actions of a data block or a view's data): call, directions, share or add to calendar. The call, directions and calendar buttons are left out for a record whose field is empty or invalid.
| Property | Type | Req. | Default | Description |
|---|---|---|---|---|
type | enum | yes | call: dials the phone number in field (shown only when it has at least 5 digits). directions: opens a route to the address or "lat,lng" in field (Apple Maps on iPhone, Google Maps elsewhere). share: opens the system share sheet with the text of field (the record's first text value when not set; copied to the clipboard where sharing is not available). calendar: adds an event from title, start, end and location (the phone's calendar in the phone app, an .ics file on the web). Values: call, directions, share, calendar. | |
label | text | Text of the button (default by type and language, e.g. Call, Directions, Share, Add to calendar). | ||
field | string | The record field the button uses: the phone number (call), the address or position (directions), the text to share (share). A dotted name reads a field of a nested object. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
title | string | calendar: the field with the event's title (up to 200 characters). Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
start | string | calendar: the date or date-time field where the event starts. The button is shown only when it holds a valid date; a date without time makes an all-day event. Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
end | string | calendar: the date or date-time field where the event ends. Without it the event lasts one hour (one day for an all-day event). Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. | ||
location | string | calendar: the field with the event's place (up to 200 characters). Values: pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$. |