Rundunrundun

Concepts

Understand the core building blocks of Rundun before you write any integration code.

Templates

A template is a reusable checklist definition. It contains sections, steps, execution settings (who can run it, identity requirements), and optional conditions between steps.

Templates are authored in the creator dashboard at my.rundun.app or via the API. Internally, templates are represented as TDL (Template Definition Language) JSON. You never write TDL by hand — the visual editor and AI generator handle that. If you're integrating via the API, you reference templates by ID.

Key facts about templates:

  • Templates are org-scoped — they belong to one organization
  • Templates are versioned — each save increments v
  • Template changes do not affect runs already dispatched — the template is snapshotted at run creation

Runs

A run is a single execution of a template dispatched to one person. When you dispatch a run, Rundun:

  1. Takes a verbatim copy of the template (the snapshot) — future template edits do not affect this run
  2. Creates a unique run link: https://rundun.app/r/:run_id
  3. Returns the link and a stable run_id

You send the link to whoever needs to complete the checklist. They open it in the Rundun mobile app and work through each step. You receive progress via webhooks.

Run statuses

Status Meaning
pending Dispatched, not yet opened by executor
in_progress Executor has opened the run and started answering
completed All required steps answered, run submitted
cancelled Executor exited before completion
expired Run link expired before the executor completed it

Once a run reaches completed, cancelled, or expired, it is permanently closed. No further updates occur.

Deep links

The run link (https://rundun.app/r/:run_id) is a universal link. On a device with the Rundun app installed, the OS intercepts the link and opens the app directly — the browser never loads. On a device without the app, the marketing site renders run info and shows app store badges.

Organizations

Every resource in Rundun belongs to an organization. When a user signs up, a personal organization is automatically created for them.

Organizations are the billing and quota unit:

  • API keys are org-scoped — all runs dispatched via a key count against that org's quota
  • runs_used_this_month and storage_used_bytes are tracked per org
  • Team organizations can be created and members invited by role

Organization roles

Role Create templates Dispatch runs View all runs Manage members Manage billing
owner yes yes yes yes yes
member yes yes org runs no no
executor no no own runs no no

The executor role is for people who only complete runs — cleaners, drivers, inspectors. They receive run assignments in-app but cannot create templates or dispatch runs.

Users

Every Rundun user has a stable internal ID in the format u-{uuid}. This ID is assigned on first login and never changes, regardless of which OAuth provider they use or whether they change their email.

Authentication is OAuth-only (Google, Microsoft, Apple). Rundun does not store passwords. The Rundun's authentication layer handles the OAuth flow; the Rundun API owns the identity layer.

Multiple OAuth providers can be linked to one u-{uuid} — a user can sign in with Google or Microsoft and always land in the same account.

Executors

The person who completes a run is the executor. Executors are always free — Rundun charges the creator, never the person completing the checklist.

How an executor identifies themselves is controlled by the template's execution.identity_required setting:

Setting What happens
"none" Fully anonymous — no sign-in, no name. Zero friction. (default)
"name" Executor enters their name before starting. No Rundun account required.
"email" Executor enters name + email. No Rundun account required.
"org_member" Executor must be a signed-in member of the org. Highest accountability.

The executor identity is recorded on the run and included in every webhook event payload under the identity field.

API keys

API keys authenticate server-to-server requests to the Rundun API.

Key format: rdk_live_ followed by 32 random characters — e.g. rdk_live_a3f9bc4d8e1f2a3b4c5d6e7f8a9b0c1d.

Key properties:

  • Org-scoped — all runs created via a key belong to that org's quota and billing
  • Shown once — the plaintext key is displayed once on creation and never again. Rundun stores only the SHA-256 hash.
  • Full org access — each key has full access to the org at MVP. Per-key scopes are planned.
  • Revocable — delete a key from the dashboard to revoke it immediately

Create and manage keys at my.rundun.app → Settings → API keys.

Webhooks

Webhooks deliver real-time events to your backend as a run progresses. You configure a webhook URL, secret, and event list per-run at dispatch time — not per-template.

Five event types are available:

Event Fires when
step.completed A step is answered
step.skipped A non-required step is explicitly skipped
run.completed All required steps answered, run submitted
run.cancelled Executor exits before completion
run.expired Run link expires before completion

Every delivery is signed using RFC 9421 HTTP Message Signatures. See Signatures for verification code.

Template Definition Language (TDL)

TDL is the JSON schema that defines all checklist templates. It is the contract between the API, the mobile renderer, the AI generator, and webhook payloads.

You don't write TDL by hand when using the dashboard. If you create templates via the API (POST /v1/templates) or generate them via AI (POST /v1/templates/generate), you work with TDL JSON directly.

See the TDL reference for the full specification.