Backend Functions

The ctx Object

Every backend function receives a ctx object and a params object. The ctx object provides access to all platform features:

ctx.tables — Database Operations

All 15 methods available on ctx.tables. These respect the table's access rules based on the calling user: a member or visitor who calls the function reads and changes only the rows the table's rules give them, and your own runs, schedules and webhooks see every row. A site function reaches only the tables of its site's one base; a table from another base behaves as if it does not exist. For another base's data, use an account function (it can only read what the caller may, unless you switch on Full data access).

ctx.tables.report — Numbers in one call

Ask a numbers question about a table — how many, how many different, total, average, smallest, biggest, middle value — for the whole table or per slice (per status, per month, per country), in one call. There is no SQL: you fill in a short question and get back a plain list of slices with numbers. Never page through rows to add them up yourself.

A report counts only the rows the run may read, exactly what getRows would give it: when a visitor or member started the function, the numbers cover just their rows; your own runs, schedules and webhooks, and ctx.service.tables.report, cover every row. A field the person may not read can't be used, and sign-in and secret fields can never be used by anyone. From a page, entities.Orders.report({ ... }) asks the same question for the visitor.

// Revenue and paid share per month this year, in Berlin time
const r = await ctx.tables.report('Orders', {
  filter: { logic: 'and', conditions: [
    { fieldId: 'Created', operator: 'greaterThanOrEqual', value: '2026-01-01' },
  ] },
  groupBy: [{ as: 'month', field: { fieldId: 'Created' }, bucket: 'month' }],
  measures: [
    { as: 'orders', fn: 'count' },
    { as: 'revenue', fn: 'sum', field: { fieldId: 'Total' } },
    { as: 'paid', fn: 'count', filter: { logic: 'and', conditions: [
      { fieldId: 'Status', operator: 'equals', value: 'Paid' } ] } },
    { as: 'paidShare', fn: 'ratio', numerator: 'paid', denominator: 'orders', decimals: 2 },
  ],
  sort: [{ by: 'month', direction: 'asc' }],
  timeZone: 'Europe/Berlin',
});
// r.rows = [{ groups: { month: '2026-01-01' },
//             measures: { orders: 12, revenue: 4510.5, paid: 9, paidShare: 0.75 } }, ...]

// Top 10 sources by leads, with each source's share of all leads
const top = await ctx.tables.report('Leads', {
  groupBy: [{ as: 'source', field: { fieldId: 'Source' } }],
  measures: [{ as: 'leads', fn: 'count' }, { as: 'companies', fn: 'countDistinct', field: { fieldId: 'Company' } }],
  percentOfTotal: 'leads',
  sort: [{ by: 'leads', direction: 'desc' }],
  limit: 10,
});

ctx.service.tables and ctx.service.files have the same methods as their regular counterparts but bypass all access rules. Use these for admin operations that need unrestricted access. They only work after a person turns on Full data access for that function: you, in the dashboard (Automations → Functions → the function → Access → Powers & secrets; in a workspace with members, the Owner or an Admin), or by tapping Apply on the card your AI shows in the chat when it asks for it (you then confirm it's you). The AI can't tap for you, and it can't say it is on before you do. The same card is how the AI changes such a function's code, secrets, allowed websites or who can run it.

// Example: admin function to get all orders regardless of access rules
const allOrders = await ctx.service.tables.getRows('Orders');
return allOrders;

ctx.fetch — External APIs

Make HTTPS requests to external services. Supports environment variable placeholders using {{VAR_NAME}} syntax.

// Call an external API with an env var for the API key
const result = await ctx.fetch('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer {{API_KEY}}' },
  body: JSON.stringify({ query: params.query }),
  timeout: 10000,
});

// result = { status: 200, data: { ... } }

ctx.files — File Operations

When the function runs for a visitor or a signed-in member, list, getUrl and delete follow each file's own rules for that person (a file with no rule is not shared, except that its creator keeps their own delete), and upload and getUploadUrl follow the folder's “create” rule, or else the site's upload gate (signed in as a member of this site). Schedules, webhooks with no sign-in, your own runs and functions with Full data access see every file the site owns. More on Files.

ctx.ai — AI inside a function

One AI call with the site owner's models: the platform models (billed as the owner's AI credits) or their own provider keys from Your AI (billed nothing here). No tools, 60-second limit, up to 4,096 output tokens, low effort by default.

const { text } = await ctx.ai.generate({ prompt: 'Summarise in one line: ' + body, maxOutputTokens: 200 });

const r = await ctx.ai.generate({
  system: 'Reply with one word: billing, bug, or other.',
  messages: [{ role: 'user', content: ticket }],
  model: 'byoai:gpt-5.4@key:…',   // one of the owner's own keys; omit for the platform model
  effort: 'low',                   // 'low' | 'medium' | 'high'
});
// r = { text, model, finishReason, usage: { inputTokens, outputTokens }, credits, ownKey }

Ask for JSON in the prompt and parse r.text in a try/catch when you need structured output. Never put a provider key in code — the owner adds keys under Your AI and the model id carries the key.

ctx.connections — built-in connectors

The owner's saved sign-ins and API keys for other services (Google, GitHub, Slack, Stripe…), managed under Automations → Set up → built-in connectors. A function uses only the ones on its own list: open the function (your site → Backend Functions → the function), then Access, and tick the app under “Authorised connections”. Until one is ticked, ctx.connections.list() answers an empty list and a call is refused. You tick them (in a workspace with members, the Owner, an Admin or a Developer). The tool runs server-side and the secret never enters the function.

// list() shows only the apps ticked under this function's Authorised connections
const slack = (await ctx.connections.list()).find((c) => c.name === 'Slack');
if (!slack) return { error: 'Slack is not ticked under this function's Authorised connections' };
await ctx.connections.call(slack.id, 'send_message', { channel: '#support', text: 'New signup: ' + email });

ctx.env — Environment Variables

// ctx.env.get resolves to the value as a string
const value = await ctx.env.get('STRIPE_SECRET_KEY');

// Write your own working values. Names must start with APP_.
await ctx.env.set('APP_ONBOARDING_STAGE', 'complete');

A function can only read a secret that a person has ticked for it: open the function, go to Access, then Powers & secrets, and tick the secret under “Secrets this function can read”. A {{NAME}} placeholder that is not ticked is sent as the literal text. Reading any other setting with ctx.env.get needs the “Read and write secrets” power. A new function has no powers on. ctx.env.set only writes names starting with APP_, and it is refused if a function with Full data access reads that setting.

Environment variables are encrypted at rest and only decrypted when your function executes. Set them in your app's Config tab. See Environment Variables for more details.

ctx.email — Sending Email

Send transactional email from your own mailbox — the default one this site may use in Automations → Sending accounts. Runs as the project/owner, so it isn't gated by the project's member-facing email access rules.

await ctx.email.send({
  to: 'customer@example.com',       // string or array of strings
  subject: 'Your order shipped',
  html: '<p>Order #123 is on its way.</p>',
  text: 'Order #123 is on its way.', // optional
  replyTo: 'support@yourapp.com',    // optional
  template: 'order-shipped',         // optional — use a saved email template instead of html/text
  data: { orderId: '123' },          // optional — template variables
});

Capped at 50 recipients per call; no monthly quota from us (your mailbox's own hourly limit applies). See Email Templates.

Sending from your own mailbox

For outreach, newsletters or anything at volume, send through your own SMTP mailbox instead. Add it under Automations → Sending accounts, then send by name — no monthly platform quota applies, and mail leaves that mailbox's domain and sending reputation.

// which mailboxes are available (no credentials are ever returned)
const { scope, accounts } = await ctx.email.accounts();
// scope: 'member' = the signed-in member's own mailboxes (empty = THEY have none)
//        'account' = your account's mailboxes (no member signed in)
// accounts: [{ id, name, fromAddress, verified, isDefault }]
// Need your account's mailboxes while a member is signed in?
//   const { accounts } = await ctx.service.email.accounts();

await ctx.email.sendVia('outreach', {
  to: 'prospect@example.com',
  subject: 'Quick question',
  html: '<p>Hello…</p>',
  unsubscribeUrl: 'https://yoursite.com/unsubscribe?e=…', // always set for marketing
});
// → { success, messageId, skipped?, fromName, fromNameOverridden }
//   skipped = suppressed recipients

await ctx.email.sendVia(null, { to, subject, html }); // null = default mailbox

// One mailbox, several identities — set the display name per send.
// The ADDRESS never changes (it is the verified, SPF/DKIM-aligned one).
await ctx.email.sendVia('outreach', {
  to, subject, html,
  fromName: "Ken's Hardware Team",   // recipients see this name
});

ctx.entitlements — Paid Access

The entitlement ledger backs the has_entitlement access rule. ctx.entitlements is the only way to write to it — grant access after a successful payment, then gate tables/files/functions/pages behind the same key. It works only after a person switches on Grant paid access for the function (Access tab, Powers & secrets): you, or in a workspace with members the Owner, an Admin, or a Developer given Give functions paid access (Team → their name → Permissions). Anyone else is told whom to ask. (In a workspace with members, Manage users stays with Developers too; Full data access is the Owner's or an Admin's only.)

Access Rules

Control who can execute your function. No rules configured = only the app owner can call it.

See Access Control for a complete guide on all rule types (including has_entitlement, function, and relationship).

Calling from Your App

In your published app's pages, import and call backend functions using the SDK:

// In your app's page code:
import { functions } from '../api/sdk';

const result = await functions.call('processOrder', {
  item: 'Widget',
  quantity: 3,
});

// result = { success: true, data: { orderId: '...' }, executionTime: 150 }

Functions are also reachable directly over HTTP (e.g., from an external webhook). The raw JSON request body is the params object — no wrapper:

POST /api/app-builder/{projectId}/functions/processOrder
Content-Type: application/json

{ "item": "Widget", "quantity": 3 }

// Response is the same shape: { success, data, executionTime }

The same access rules apply either way — an unauthenticated or under-permissioned external caller gets the same deny response a logged-out SDK call would.