#Introduction & Overview

Helm is an entity-driven workflow platform. You model your domain as flexibly-typed entities, relate them, query them over REST or GraphQL, automate them with workflows and jobs, and surface them to end users as bridge apps — all multi-tenant and access-controlled from the ground up.

Everything is reachable through one HTTP API gateway. You authenticate with a Personal Access Token, and every request is isolated to your tenant.

New here? Read Core Concepts for the mental model, then follow the Canonical Example end to end.

#The surfaces you build on

Helm is a set of cooperating services behind the gateway. As an API consumer you interact with a handful of surfaces, each with its own guide:

#How the pieces fit together (three layers)

It helps to think in three layers:

1. Definition — the design-time spec of behavior or structure: a workflow definition, a job definition, an app spec. Definitions are reusable and can be shared across tenants.
2. Activation — a tenant's use of a definition: its configuration, triggers, integrations, credentials, and principal overrides. Workflows are activated on /workflows; apps on /apps.
3. Access — who can see and do what: policies, role assignments, intra-tenant grants, and cross-tenant shares.

A typical build moves left-to-right: define a data model and a workflow, then activate it for your tenant, then control access to it.

#Glossary

• Entity — a single data object (e.g. one Project). Belongs to an entity type; its attributes JSON is shaped by that type's schema.
• Entity type — the definition of a kind of entity: its schema, which attributes are indexed/sortable/searchable, and its identifier.
• Relationship rule — a permitted connection between two entity types (e.g. Project → Task). A relationship is a concrete instance of a rule between two entities.
• Schema — a JSON Schema document that validates an entity type's attributes.
• Workflow — an automation: an ordered set of steps that run actions. Steps may run inline actions or call a referenced job.
• Job — a reusable unit of work invoked by a workflow (or run inline).
• Action — a single operation a step performs (create an entity, call HTTP, send an event, …).
• Trigger — what starts a workflow: an event, a cron schedule, or a webhook.
• App spec — the definition of a bridge app: its dashboards, pages, widgets, providers, and principals.
• Widget — a config-driven UI building block rendered by a bridge app (see the Widget Catalogue).
• Smart value — an expression ({{ … }}, $jsonata, $if) evaluated against a runtime context (see Smart Values).
• Principal — an actor: a user, a team, or a policy.
• Policy — a named bundle of permissions a principal can be assigned.
• Grant — an intra-tenant authorization of a principal to act on a resource.
• Share — a cross-tenant, read-only authorization that makes a resource visible to another tenant (see Shares & Grants).
• Tenant — an isolated account boundary; all data is tenant-scoped.

#Conventions at a glance

• Auth: HTTP Basic with a PAT — Authorization: Basic base64(client_id:client_secret).
• JSON: snake_case fields, UUID ids.
• Errors: a stable envelope — { "error": { "status", "code", "message", "details" } }. Rely on the HTTP status, not parsing.

See Auth & API Gateway for the full contract, and the API reference for every endpoint.