Getting Started

What is a WorkApps App?

A WorkApps app is a static HTML/JS bundle that runs in the browser and calls the WorkApps Data API to read and write structured data. There are two app types:

Utility Apps — static tools with no server-side data (calculators, converters, reference tools)
Workflow Apps — data-driven apps that store records via entities and the Data API

This documentation covers Workflow Apps.

Architecture

Your AppHTML / JS / CSS

Your static app — runs entirely in the browser. You build the UI; WorkApps handles everything else.

WorkApps JS SDKsdk.workapps.tech/v1.js

Your only dependency. Include it with a <script> tag — no build step needed.

Data API

The SDK talks to this on your behalf — you never call it directly. No CORS, no tokens, no raw HTTP.

WorkApps Backend

Auth & sessionsSchema validationStorageRole enforcement

Key points:

Your app runs on the same origin as WorkApps — no CORS needed.
Authentication is handled by WorkApps — your app never implements login.
The SDK reads appId from window.__WORKAPPS__ — never hardcode it.
All Data API calls go through the SDK — never use raw fetch() for those.

Two identifiers: `appId` and app URL

WorkApps uses two different identifiers for the same app, and each has a specific purpose:

Identifier	Example	Where you see it	When to use it
`appId` (ULID)	`01JA7QG2...`	`window.__WORKAPPS__.appId`, `X-WorkApps-AppId` header, outbound webhook `app_id` field	SDK requests, webhook handlers, anywhere the API contract requires a stable machine identifier
App slug	`task-tracker`	The `/apps/task-tracker/...` URL in the admin UI, shared links, bookmarks	Navigation, linking, anything a human reads

The ULID is frozen per app — it never changes, even if the owner renames the app. It's the identifier the SDK, API, and webhook subscribers rely on.

The slug can change when an admin renames the app. When that happens, old URLs (both the previous slug AND the ULID form /apps/{ulid}/...) continue to resolve — the platform redirects them to the current slug automatically. Integrations that store a URL don't need to track renames, but integrations that store an identifier should always store appId, not the slug.

Common mistakes

❌ Storing the admin URL in your integration database. If the admin later renames the app, your URL still works (thanks to the redirect), but the display URL drifts from the one users now see in their browsers. Store appId and construct the URL from it when you need to display one.
❌ Passing the slug to the SDK. The SDK reads appId from the bootstrap; you should never pass a slug into any SDK method.
❌ Parsing the URL to extract an identifier. The slug can change; the URL structure can change. Use window.__WORKAPPS__.appId when you need the app identity at runtime.

Building Your First App

1. Design your schema

Decide what data your app needs to store. Each concept becomes an entity (like a database table), and each property becomes a field.

For example, a task tracker might have one entity:

Entity	Key	Fields
Tasks	`tasks`	`title` (text, required), `status` (select: open/done), `due_date` (date)

See Field Types for all available types.

2. Write your app

Load the SDK and use it to read/write records:

1<!DOCTYPE html>2<html>3<head>4  <title>My App</title>5</head>6<body>7  <script src="https://sdk.workapps.tech/v1.js"></script>8  <script>9    const sdk = new WorkAppsSDK();1011    async function init() {12      const bootstrap = await sdk.getBootstrap();13      const canEdit = ['editor', 'admin'].includes(bootstrap.role);14      // show/hide edit controls based on role...1516      const result = await sdk.listRecords('tasks', { sort: 'due_date:asc' }); // 'tasks' — entity key17      // render result.data...18      console.log(result.data);19    }2021    init();22  </script>23</body>24</html>

See SDK: Records for the full CRUD reference.

3. Set up your schema in WorkApps

Log in to app.workapps.tech
Click New App, give it a name, and choose Workflow App
Open the Schema Builder and create each entity with its fields

4. Upload your app

Drop your HTML/JS/CSS files directly into the upload area (or zip them first). WorkApps accepts individual files or a single ZIP — both work.

Your app must have an index.html at the root.

5. Publish

Click Publish to make your app live. WorkApps validates the files and schema, then serves your app at your org's subdomain.

What NOT to Do

Never hardcode appId — the SDK reads it from window.__WORKAPPS__ automatically
Never call fetch() directly for Data API requests — always use the SDK (file uploads to storage are the one exception — see File Uploads)
Never implement authentication — WorkApps handles login/session
Never use offset pagination — always use cursor-based pagination
Never include a backend — WorkApps apps are static; the Data API is your backend