TypeScript SDK
The SDK wraps every command in a typed method. Method names match command names, so scaffold.task.create() is the task_create action of the task_write tool and POST /v1/tasks.
Install
npm install @scaffold-llc/sdkCreate a client
import { Scaffold } from "@scaffold-llc/sdk"; const scaffold = new Scaffold({ token: process.env.SCAFFOLD_TOKEN, maxRetries: 2, timeout: 30_000,});Options
tokenstringA token from Settings, then Apps and tokens. Defaults to SCAFFOLD_TOKEN. It acts as you in its workspace, so never send it to a browser.
baseUrlstringDefaults to https://scaffold.llc. Must be https, or http on localhost.
timeoutnumberMilliseconds per request. Defaults to 30000.
maxRetriesnumberRetries for 429 and 5xx responses, with backoff. Defaults to 2.
versionstringThe API version every request sends. Defaults to the SDK's own, 2026-10-01.
appSecretstringYour app's secret, for the app_auth methods its server calls for its users. Defaults to SCAFFOLD_AUTH_SECRET, which every server app gets. Never send it to a browser.
Call a command
Arguments are one object. Answers are plain objects with the same field names as the HTTP API.
const task = await scaffold.task.create({ workspace_id: "ws_01jbz5m8q6e4w3r2t1y0v9h8g7", title: "Ship the booking page", status: "doing", assignee: "me", labels: ["launch"], due: "2026-11-04",});Lists and pages
List methods return one page and its next cursor. Loop with for await and the SDK fetches each next page as you reach it.
for await (const task of scaffold.task.list({ workspace_id, status: "doing" })) { console.log(task.id, task.title);} // Or one page at a timeconst page = await scaffold.task.list({ workspace_id, limit: 50 });const next = await scaffold.task.list({ workspace_id, starting_after: page.next_cursor });Errors and retries
Failed calls throw a ScaffoldError with the same type as the HTTP error. Rate limits and unavailable answers are retried for you, after the wait Retry-After asks for.
import { Scaffold, ScaffoldError } from "@scaffold-llc/sdk"; try { await scaffold.run.create({ workspace_id, agent: "planner", prompt: "Plan next week" });} catch (err) { if (err instanceof ScaffoldError && err.type === "credits_exhausted") { console.log("Out of credits. Top up in Settings, then Billing."); } else throw err;}Safe retries for writes
Pass an idempotency key and a retried write returns the first result instead of running twice. Keys last 24 hours.
await scaffold.task.create( { workspace_id, title: "Ship the booking page" }, { idempotencyKey: "launch-2026-10-29" },);Your app's users
Your app's server signs its users up and in with scaffold.app_auth.sign_up(), sign_in(), email_send(), verify() and password_reset(), which need no token. Pass each user's address as clientIp, and each user spends their own rate limits while your server gets a larger budget of its own, rather than all your users sharing one. Only a call with the app's secret may pass an address, so a browser can't. Your app sits behind Scaffold's edge, which sends each visitor's address as X-Forwarded-For: in Express, set trust proxy to 1 so req.ip is that address rather than the edge's. Keep SCAFFOLD_AUTH_SECRET on the server.
import { Scaffold } from "@scaffold-llc/sdk"; // In your app's server, which Scaffold gives SCAFFOLD_AUTH_SECRETconst scaffold = new Scaffold(); // Scaffold's edge sends each visitor's address as X-Forwarded-For, so req.ip is theirsapp.set("trust proxy", 1); app.post("/sign-in", async (req, res) => { const session = await scaffold.app_auth.sign_in( { project_id: process.env.SCAFFOLD_PROJECT_ID, email: req.body.email, password: req.body.password }, { clientIp: req.ip }, ); res.json(session);});Types
import type { Task, Run } from "@scaffold-llc/sdk"; function summary(task: Task): string { return `${task.title} is ${task.status}`;}