reference

The AI - Chat Message node enables conversations with large language models (LLMs) from multiple providers including OpenAI, Anthropic, Google AI, and Groq. It supports dynamic message templates with variable interpolation, streaming responses, extended thinking, and AI actions (tool use).

The AI - Compute Embedding node converts text into high-dimensional vector representations (embeddings) that capture semantic meaning. These embeddings can be used for semantic search, similarity comparison, and vector context operations.

The AI - Data Extraction node uses large language models to extract structured data from unstructured text content. It can extract data matching a defined schema, optionally creating Records automatically upon extraction.

The AI - Image Generate node creates images based on text prompts using AI image generation models. It returns the generated image as a file that can be used in Experiences or stored.

Canonical model list for AI nodes, including deprecated model fallback mappings.

The AI - Router node evaluates input variables and configured route options, then chooses a single option to continue the run. Each option can optionally define a structured output schema for AI-generated data when that option is selected.

The AI - Text to Speech node generates realistic spoken audio from text input using OpenAI's text-to-speech models. It supports multiple voice options and quality levels, returning an audio file that can be used in Experiences or stored.

The AI - Transcribe node converts spoken audio into text using OpenAI's Whisper model. It supports various audio formats and can handle multiple languages.

The AI - Vector Context Add node stores text embeddings in a vector context, enabling later semantic search operations. It automatically computes embeddings and indexes them with optional labels for filtering.

The AI - Vector Context Query node performs semantic search over stored embeddings in a vector context. It returns the most similar content based on embedding distance, with optional filtering by labels.

The AI - Vector Context Remove node deletes embeddings from a vector context. It can remove specific embeddings by ID or remove all embeddings matching certain label criteria.

The Auth - Magic Link Generate node creates a secure, single-use authentication link that users can click to log in without a password. The link is typically sent via email and expires after a configurable period.

Gets an OAuth access token for a configured OAuth credential. The token is automatically refreshed when needed and returned as a wrapped secret value.

The Auth - Space Identity Create node creates a new Space Identity within a Space, allowing users to authenticate and access the Space's Experiences. It assigns a role to the Space Identity, determining the user's permissions.

This reference documents all currently defined Experience block types in Ligantic.

Media block for rendering audio sources with optional sizing, replaced-element properties, and media control settings.

Container block used for layout composition and optional semantic HTML mapping. It accepts the shared properties and can contain nested children blocks.

Interactive block that renders Text and Image children and triggers configured actions.

Media block for rendering images. Supports URL/file/datum-backed sources, explicit dimensions, replaced-element presentation options, and optional state overrides.

Interactive data-entry block with component variants for text/date input and optional Flow triggers.

Clickable navigational block. Its destination is set by to: a URL, an Experience, or an auth action. It also takes the shared block style, layout, and data properties, and it restricts which blocks it can contain.

Block for rendering textual content. Supports plain strings, rich content objects, or a datumReference, with optional typography and semantic HTML element configuration.

Media block for rendering video sources, with intrinsic dimensions and optional media control settings.

Data-visualisation block with component-specific configuration for WordCloud, BarChart, and Map.

The Browser - Actions node executes a sequence of automated actions on a browser page. It supports navigation, clicking, typing, key presses, and content extraction (text, HTML, screenshots). Each action in the sequence is executed in order.

The Browser - Navigate node opens a headless browser and navigates to a specified URL. It creates a browser page that can be used by subsequent Browser - Actions nodes for web scraping, automation, or testing scenarios.

Canvas is the admin-only, versioned authoring surface for a Space. This section documents its snapshot format, its operations, and its access rules.

Canvas access requires both of these conditions:

Conversion turns a literal node — a definition held only as an artifact — into a first-class Schema, Experience, or Flow, and replaces the literal node with a reference node.

Canvas actions are available in the Studio Canvas editor. They are not part of the public REST API or the ligantic CLI. Access rules are in Canvas Access.

A flow:literal node holds a Flow definition. Running the node starts a run of that Flow.

Ingestion turns an uploaded file into an artifact on a Canvas. It is the only way external content enters a Canvas.

A Canvas is a named authoring surface in a Space. Each saved change to its content is kept as a version. Versions are not edited or deleted.

Content produced by table extraction and Schema derivation is accepted automatically when it is created. Users cannot review, accept, reject, supersede, edit, or re-run it in Studio or through the API.

A Canvas snapshot is the complete shared state of a Canvas at one version. Per-user client state, such as selection and the camera, is not part of it.

Canvas data is included in Space export and import, whether or not Canvas is available in the Space.

Tabular operations read the content of a Canvas node and produce previews, extracted tables, and Schema literals.

Conditional branching node that evaluates a boolean condition and directs the run down one of two paths. Supports both control flow mode (branching the run) and data mode (selecting between values).

Routes the run or data based on a single input value matched against configured cases. Supports control-flow branching and data-selection modes.

Delays the run for a specified number of seconds. The wait duration can be set as a static value or dynamically via an input handle.

Provides access to run context values. Use this node to retrieve metadata about the current run, such as the Space ID, run ID, or the identity of the user who triggered the Flow.

Evaluates a mathematical or logical expression with variables. Supports arithmetic, string manipulation, date/time operations, similarity functions, and array operations. Use this node for calculations, transformations, and complex data logic.

Provides a static data value of any supported type. Use this node to inject constant values into your Flow, such as configuration strings, default numbers, or structured objects.

An entity context wraps a region of an Experience so that descendant blocks (Input, Button, and Text blocks) can read from and write to the same underlying Record. Configure it from the Entity Context section of the block settings panel on any block that supports the entityContext prop (such as Box, Button, or Link blocks).

Decides the HTTP response of an Endpoint (see Custom Endpoints) whose response source is Controlled by flow: the status, headers (including redirects and cookies), and a typed JSON body. The first response node a run reaches is the response; the node ends its path.

Endpoints let a Space expose a published Flow at a caller-chosen HTTP method and path. They are the programmatic counterpart to Experiences: where an Experience renders a UI at a path, an Endpoint returns a JSON body at a path.

This section contains reference documentation for Ligantic Experience schemas and block types.

Block states entries are optional and support three id classes:

The File - JSON Parse node reads a JSON file and parses its contents into a structured data object, validated against a configurable Schema. It supports standard JSON as well as JSONC (JSON with Comments) format and allows trailing commas for more lenient parsing.

The File - XLSX Read node reads spreadsheet files (XLSX, CSV, TSV) with configurable parsing options and extracts data as an array of records. Each row becomes an object matching the configured Schema, with columns mapped to properties.

The File - ZIP Create node builds a ZIP archive from file entries, with size and count limits. Entries can be grouped by folder, provided as flat folder/file rows, or placed as bare file entries at the archive root; the archive name can be a static string or a single-line template resolved at process time.

The File - ZIP Extract node extracts files from a ZIP archive, applying security validations to prevent malicious archives from causing harm. It supports file pattern filtering and size limits, returning the extracted files as an array that can be processed by other nodes.

The Experience - Build URL node resolves the published path of an Experience and builds a shareable URL, targeting the cloud or a Ligantic app endpoint. Optional datum inputs are resolved and appended to the URL.

Renders a published Experience with the app target in headless Chromium using print media mode, then creates and uploads a PDF file. The node emits the created PDF as a file handle for downstream nodes.

Cancels a running or scheduled Flow run. Use this node to stop a previously scheduled Flow from running, or to terminate an in-progress run.

Runs another Flow, optionally scheduling it for a later run. Allows Flows to call other Flows, passing inputs and receiving results. Supports both synchronous (inline) and scheduled (background) run modes.

Returns a result value from a Flow run. The result is made available to the caller when the Flow completes. A Flow can have multiple result nodes for different run paths.

Entry point for Flow runs. Defines the inputs that a Flow accepts and makes them available to downstream nodes. Every Flow must have exactly one trigger node.

The Integration - HTTP node performs HTTP requests to external URLs, supporting all common HTTP methods, custom headers, query parameters, request bodies, and OAuth 1.0a authentication. It can return parsed responses matching a defined schema.

The Integration - SMTP node sends emails through an SMTP server. It supports various email formats including plain text, HTML, and rich content with automatic text fallback. The node can handle attachments and supports common email features like CC, BCC, and reply threading.

The Integration - SQL Connect node creates a connection to a SQL database that can be used by subsequent Integration - SQL Query nodes. It supports PostgreSQL and Microsoft SQL Server databases with various authentication options including connection strings and individual credential fields.

The Integration - SQL Disconnect node explicitly closes a database connection that was established by an Integration - SQL Connect node. While connections are automatically cleaned up at the end of the top-level run, this node allows for explicit resource management within longer-running Flows. Shared SQL credential mode in Integration - SQL Query nodes is managed automatically and does not require a disconnect node.

The Integration - SQL Query node executes SQL queries against a database connection established by an Integration - SQL Connect node. It supports parameterised queries to prevent SQL injection, validates queries for dangerous operations, and returns results matching a configurable schema.

Aggregates list data using count, countDistinct, sum, avg, min, and max. Supports optional grouping and can return either the first aggregate row or the full result list.

Filters, sorts, and paginates an array of items. Apply filter conditions to select matching items, sort by multiple fields, remove duplicates, and limit results.

Iterates over each item in a list and runs the nodes connected to the trigger output for each one. Creates a scoped context for each iteration where the current item is available. Collects results from all iterations into an output list. Supports both parallel and sequential modes.

The Media - Audio Process node performs audio processing operations on audio files. It supports a variety of operations including speed adjustment, volume normalisation, noise reduction, segment extraction, format conversion, pitch shifting, and fade effects.

The Media - Video - Audio - Extract node reads a video file, extracts the first audio stream, and outputs a new audio file.

This reference documents all available Flow node types in Ligantic. Nodes are the building blocks of Flows — visual workflows whose runs execute in the background.

Creates a new Record in a specified Schema. The created Record can be queried or modified by subsequent nodes in the Flow.

Links a source Record (from) to a target Record (to) using a configured relationship version. Depending on relationship cardinality, the operation creates a relationship, repoints an existing relationship, or leaves an exact active relationship unchanged.

Combines selected property values into a Schema-validated object, or validates a data input against a non-object Schema. The configured Schema can be inline or reference an existing Schema.

Extracts specific properties from an object or Record. Creates individual output handles for each selected property, allowing you to access nested fields without using expressions. Automatically adapts output handles based on the connected object's Schema.

Queries Records based on filter criteria. Supports complex filtering, pagination, and ordering. Returns matching Records with metadata. Results can be processed, displayed, or passed to downstream nodes.

Queries relationships between Records to find linked Records. Given either a source Record or target Record, finds the corresponding linked Record via a specific relationship type. Returns Record IDs for further processing.

Removes Records that match filter criteria. Supports querying by any property and removes matching Records along with their relationships. Returns the removed Records for downstream processing.

Removes relationships between Records. Supports three modes: unlinking a single specific relationship, removing all outgoing relationships from a Record, or removing all incoming relationships to a Record.

Updates an existing Record with new values, modifying only the specified properties and preserving unchanged data. Handles file uploads automatically when properties contain files.

This reference documents all available field types for defining Schemas in Ligantic. Schemas define the structure of your data and are the foundation for both Experiences and Flows.

The official TypeScript SDK (@ligantic/sdk) and command-line interface (@ligantic/cli) give external developers one coherent way to authenticate, manage Spaces and Resources, work with Records, and invoke and inspect Flows against the Ligantic API.

@ligantic/cli provides the ligantic binary. It is a thin layer over @ligantic/sdk: the same result-based operations, rendered as JSON when stdout is not a terminal (scripts, agents, CI) and as tables on a terminal. See Output and Errors.

These commands are generated from the Ligantic OpenAPI spec, so the CLI covers every public API operation. The hand-written commands in the CLI command reference take precedence where both exist: for example records list is hand-written, and records json-patch is generated. Find a command with ligantic cli search "<what you want to do>".

@ligantic/sdk is a thin, result-based, versioned mirror of the Ligantic OpenAPI v1 surface. Every operation returns Promise<LiganticResult<T>> and request methods return failures as the Err side (no thrown API/transport errors).

The Secret - Get node retrieves a secret value from the secure secret store. Secrets are stored encrypted and are only decrypted when needed. The retrieved value is returned as a wrapped secret that can be passed to other nodes requiring credentials.

The Secret - Remove node deletes a secret from the secure secret store. Use this node to clean up credentials that are no longer needed or to implement credential rotation workflows.

The Secret - Set node securely stores a secret value in the secret store. Secrets are encrypted at rest and can be retrieved later using the Secret - Get node. Use this node to store API keys, passwords, tokens, and other sensitive credentials.

The Secret - Unwrap node extracts the plain text value from a wrapped secret. While most nodes that need secrets can accept wrapped values directly, this node is useful when you need the actual string value for custom processing.

The Stream - Collect node consumes an asynchronous stream (such as LLM streaming responses) and processes each chunk as it arrives. It enables accumulator patterns where results build up incrementally, useful for streaming text aggregation, real-time processing, or tracking stream progress.

The System - Ingest node ingests incoming data using a format adapter.

Converts rich content to serialised output. By default it serialises to plain text, and it can optionally serialise to HTML. Any included media is converted to pre-signed URLs for access.

The Text - Extract List Items node parses Markdown-formatted text and extracts items from the first list found in the document. It supports both ordered and unordered lists, including GitHub Flavored Markdown (GFM) syntax. Each list item is returned as a trimmed string in an array.

Parses PDF files into structured content. Extracts text with page-level granularity, generates page images, and splits content into chunks.

Parses HTML string into rich content. Converts HTML elements into structured content nodes including paragraphs, headings, lists, links, and more. Optionally resolves relative URLs in the content.

Parses Markdown text into rich content. Converts Markdown elements into structured content nodes. Handles code blocks, including automatic stripping of Markdown code fences if wrapping the entire content.

The Text - Recursive Split node divides text into smaller chunks suitable for processing by language models or other text analysis tools. It splits on natural boundaries (paragraphs, lines, words) where possible, while respecting the configured chunk size. Overlapping between chunks ensures context is preserved across boundaries.

Renders a rich-content template with variable substitution. Insert variables through the template editor, then connect each generated input handle to the value it should render. It generates dynamic content such as messages, emails, or prompts.

The Text HTML Query and Transform node manipulates HTML through a sequence of configurable operations. It can query elements using CSS selectors to extract content (HTML, text, or attributes) and remove unwanted elements from the document. Each query operation creates a dynamic output handle for its results.

The UX - Action node triggers actions in the user interface of an Experience. It can navigate to different pages or Experiences, update data in the UI, trigger data refetches, or trigger file downloads. This enables Flows to control the user experience dynamically.

The UX - Message node sends a notification message to users in an Experience. It supports different severity levels (success, info, warning, error) and can include dynamic content through variable interpolation. Messages are displayed as toast notifications in the user interface.