---
title: "Workflow SDK reference"
description: "Complete TypeScript SDK for Grid82 workflows: triggers, db operations, ai decisions and generation, step sleeps, approvals, and http egress."
canonical: "https://grid82.com/docs/developers/sdk/workflow-sdk"
updated: "2026-11-20"
---

# Workflow SDK reference

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

```ts
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

| Trigger                                           | `trigger` payload fields      | Notes                                                                                                                                                                  |
| ------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule(pattern, { timezone? })`                | `firedAt`, `runId`            | Accepts 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`, `runId`             | Fires when a new record satisfies optional `when`                                                                                                                      |
| `record.updated("App.Table", { fields?, when? })` | `record`, `previous`, `runId` | Fires when listed fields change and record satisfies `when`                                                                                                            |
| `record.deleted("App.Table")`                     | `previous`, `runId`           | Fires after deletion                                                                                                                                                   |
| `manual({ input })`                               | `input`, `runId`              | Field types: `"text"`, `"number"`, `"boolean"`, `"date"`, `"record"` (append `"?"` for optional inputs)                                                                |
| `webhook({ input })`                              | `input`, `runId`              | Studio 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:

| Method                                                | Behaviour                                                          |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `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`)

```ts
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:

| Method                                                         | Return value                                                                                               | Model options                                             |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `ai.yes(label, { question, context })`                         | Probability `0..1`                                                                                         | Decision 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.
