Before you start
Workflow
- 1For the write example below, follow the managed-database guide to publish a customers table with id and name columns. Set PERMUTE_DATABASE_ID to that database ID. A read-only portal does not need this customer-creation action.
- 2Create an action with business action creation admin permission. Saving requires Edit draft on the action and Read on each selected source. Publishing requires Publish on the action and source Admin to delegate the declared capabilities. Saving never executes code or grants those capabilities.
- 3Save the handler, input and output contracts, invocation permission (read, write, or admin), and published schema bindings as one draft. Set llm: true when the handler calls llm(); the action failures and retries guide covers its limits.
- 4Publish the exact draft through client.revisions, then invoke it with a stable requestId and input.
Project setup
bun add @permute/sdk @paralleldrive/cuid2
Example
import { PermuteClient } from '@permute/sdk';
import { createId } from '@paralleldrive/cuid2';
const client = new PermuteClient({ apiKey: process.env.PERMUTE_API_KEY! })
.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);
const databaseId = process.env.PERMUTE_DATABASE_ID!;
const schema = await client.databases.definition(databaseId);
if (!schema.published) throw new Error('Publish the database schema first');
// Keep the ID after creation. Set PERMUTE_ACTION_ID to edit this action later.
const action = process.env.PERMUTE_ACTION_ID
? await client.actions.get(process.env.PERMUTE_ACTION_ID)
: await client.actions.create({ name: 'Create customer' });
console.log('Action ID:', action.id);
const current = await client.actions.definition(action.id);
const contract = {
type: 'object',
description: 'Create one customer. The ID must be new; an existing ID is a conflict. Returns the saved ID and name.',
properties: {
id: { type: 'string', minLength: 1, description: 'A new customer identifier; retain it when retrying.' },
name: { type: 'string', minLength: 1, description: 'Customer name.' },
},
required: ['id', 'name'],
additionalProperties: false,
examples: [{ id: 'customer_example', name: 'Acme' }],
};
const saved = await client.actions.saveDefinition(action.id, {
expectedDraft: current.draft
? { revisionId: current.draft.revisionId, sequence: current.draft.sequence }
: null,
definition: {
source: "exports.handler = ({ input, db }) => { db.insert('customers', input); return input; };",
inputSchema: contract,
outputSchema: { ...contract, description: 'Saved customer ID and name, returned only after the write commits.' },
invokePermission: 'write',
sources: [{
sourceId: databaseId,
revisionId: schema.published.revisionId,
readTables: [],
writeTables: ['customers'],
}],
},
});
const history = await client.revisions.list(action.id);
if (history.draft?.revisionId !== saved.revisionId) {
throw new Error('Action draft changed; review before publishing');
}
await client.revisions.publish(action.id, { expectedVersion: history.version });
// Persist this request before sending if retries must survive a process restart.
const request = { requestId: `areq_${createId()}`, input: { id: `cust_${createId()}`, name: 'Acme' } };
const receipt = await client.actions.invoke(action.id, request);
console.log(receipt.revisionId, receipt.output);
// After a lost response, retry with the identical requestId and input.Permissions and publication
The author delegates database tables, connector accounts, or SDK resource permissions when saving and publishing. Callers need an explicit Run grant on the action, or an existing level-based grant that meets its invocation threshold. SDK-only and connector-only actions need no managed database; use the narrowest action contract that fits the operation.
client.actions.list and client.actions.get expose the current published input/output schemas, invocation permission, and declared capabilities without source code. The contract’s effects list only changes outside the action: managedDataWrites, connectorCalls and platformMethods; AI use is not listed. An unpublished action has a null contract. client.actions.definition requires View code permission and returns draft and published definitions. History, restore, and publication use client.revisions; restoring does not publish or execute the action.
Hosted apps bind an exact published action revision in apps.saveSite and call it through @permute/sdk/app. The app release and app data-access guides cover bindings and browser calls. API-key invocations use the current published action, while a retry retains the revision selected by its first attempt.
Require explicit scope before implementing writes
Before implementing a requested write, establish the destination system and account, affected records and fields, allowed operation (create, update, or delete), trigger, and expected result. Ask about missing consequential details; do not infer them from a screen label or fill gaps with broader write capabilities. Existing explicit authorization can be reused within its scope; do not ask again merely because implementation has several steps.
Writes require more than a read action with a Save button. Define input validation, the narrowest delegated scope, conflict handling, confirmation where appropriate, and how retries or uncertain outcomes are reconciled. External effects cannot be rolled back with local database changes. Keep unfinished or unapproved write paths out of the published app and its grants.
Verify against an approved test destination or fixture before any authorized production execution. A failed request does not prove nothing changed. Never test a write against production simply to discover whether the connected account permits it.