Grid82
grid82.comJoin the waitlist
DevelopersWorkflow SDK

Workflow SDK reference

Complete TypeScript SDK for Grid82 workflows: triggers, db operations, ai decisions and generation, step sleeps, approvals, and http egress.

Every workflow imports workflow and trigger helpers from "grid82:workflow". Every SDK operation inside the handler takes a unique literal string label as its first argument; Grid82 uses these labels to draw the live diagram and correlate paused runs across replays.

Defining a workflow and triggers

TypeScript
import { workflow, schedule, record, manual, webhook } from "grid82:workflow";

export default workflow(
  {
    name: "Weekly pipeline digest",
    trigger: schedule("weekdays 09:00", { timezone: "Europe/Paris" }),
    apps: ["Sales CRM"],
    egress: ["hooks.slack.com"],
    maxWrites: 500,
  },
  async ({ trigger, db, ai, step, approval, http }) => {
    // ...
  },
);

Supported triggers

Triggertrigger payload fieldsNotes
schedule(pattern, { timezone? })firedAt, runIdAccepts cron strings or phrases ("weekdays 09:00", "every day 07:30", "every monday, thursday 18:00", "monthly 1 09:00", "every hour", "every 15 minutes")
record.created("App.Table", { when? })record, runIdFires when a new record satisfies optional when
record.updated("App.Table", { fields?, when? })record, previous, runIdFires when listed fields change and record satisfies when
record.deleted("App.Table")previous, runIdFires after deletion
manual({ input })input, runIdField types: "text", "number", "boolean", "date", "record" (append "?" for optional inputs)
webhook({ input })input, runIdStudio app workflows only; endpoint https://{suite}/hooks/{app}/{workflow} (max 64 KB JSON, deduplicated by webhook-id)

Database operations (db)

Access tables by exact display name (db["Sales CRM"].Deals or db.Sales.Deals). Field values use display names (record["Net value"]), select options use labels ("Won"), and links return [{ id, label }] objects:

MethodBehaviour
db.App.Table.find(label, { where?, sort?, limit? })Returns matching records (limit default 100, max 1,000)
db.App.Table.get(label, idOrLink)Fetches one record by ID or link field value (or null)
db.App.Table.create(label, fields)Creates a record and returns it
db.App.Table.update(label, idOrLink, fields)Updates a record ("now" and "today" supported for date fields)
db.App.Table.delete(label, idOrLink)Deletes a record

where supports plain equality ({ Stage: "Proposal" }), typed operators (gt, gte, lt, lte, before, after, is_any_of, contains, is_empty, is_checked), and or: [{ ... }, { ... }].

Durable steps and waits (step)

  • step.do(label, () => ..., { retries?: 3, timeout?: "5 minutes" }). Wraps synchronous computation, data formatting, Date.now(), or Math.random() in a memoized durable step (retries 0..10, timeout up to "30 minutes").
  • step.sleep(label, "2 days") / step.sleepUntil(label, isoDate). Pauses execution at zero cost for up to 1 year.

Approvals (approval.ask)

TypeScript
const decision = await approval.ask("Approve large discount", {
  role: "Sales Manager",
  question: "Approve 25% discount on Northwind renewal?",
  show: { Deal: deal.Name, Amount: deal["Net value"] },
  timeout: "7 days", // default 7 days, max 30 days
});
// decision: { approved: boolean, by?: string, at?: string, note?: string, timedOut?: boolean }

AI steps (ai)

Use decision steps (ai.yes, ai.choose, ai.score) for classification and routing, and generative steps (ai.write, ai.extract) for drafting text or structured extraction:

MethodReturn valueModel options
ai.yes(label, { question, context })Probability 0..1Decision model (fast, sub-second)
ai.choose(label, { question, options, context }){ choice, probabilities, confidence }Decision model
ai.score(label, { question, context, scale? }){ score, level, probabilities, confidence }Decision model
ai.write(label, { instructions, context?, output?, model? })Plain text or structured output object"fast" (default), "smart", or any OpenRouter model ID
ai.extract(label, { from, output, model? })Extracted object matching output types ("string", "number", "boolean", "string[]", "number[]")"fast" (default), "smart", or OpenRouter ID

Outbound HTTP (http)

Studio app workflows may call domains listed in egress via http.get(label, url, headers?) and http.post(label, url, body, headers?). To protect webhook tokens, store the full destination URL in a suite secret and pass "secret:SECRET_NAME" as the url argument. Secrets cannot be interpolated inside request headers or JSON bodies.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search Grid82 documentation and read it in full, instead of answering from memory.

https://grid82.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://grid82.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.