Search documentation

AI - Chat Message

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).

AI - Compute Embedding

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.

AI - Data Extraction

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.

AI - Image Generate

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.

AI - Model Reference

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

AI - Router

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.

AI - Text to Speech

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.

AI - Transcribe

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

AI - Vector Context Add

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.

AI - Vector Context Query

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.

AI - Vector Context Remove

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.

Audio

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

Authentication and Key Storage

This explains how the SDK and CLI authenticate, where the CLI keeps your API key, and how the CLI decides which Space, key, and base URL to use.

Auth - Magic Link Generate

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.

Auth - OAuth Get Access Token

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

Auth - Space Identity Create

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.

Box

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

Browser - Actions

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.

Browser - Navigate

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.

Button

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

Canvas Access

Canvas access requires both of these conditions:

Canvas Conversion

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 Editor Actions

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.

Canvas Flow Literal Runs

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

Canvas Ingestion

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

Canvas Lifecycle and Versions

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.

Canvas Reference Overview

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

Canvas Review and Provenance

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.

Canvas Snapshot Format

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 Space Transfer

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

Canvas Tabular Preview and Extraction

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

CLI Command Reference

@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.

Control - If

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).

Control - Switch

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

Control - Wait

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.

Custom Endpoints

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.

Data - Context

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.

Data - Expression

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.

Data - Literal

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.

Data - Recurrence

Works with the value of a recurrence field, such as "weekly on Monday, Wednesday and Friday at 5:00 PM". Depending on its mode, the node lists the occurrences in a date range, finds the next or previous occurrence, or checks whether a date/time falls on an occurrence.

Data - Solve

Finds an optimal solution to a linear or mixed-integer linear model written in CPLEX LP format. Models describe an objective, constraints, bounds, and optional integer or binary variables; they are not executable JavaScript.

Editable Rows

Rows of a list can be edited in place: an Input block inside a For Each over a query writes to the Record the row shows, and a CRUD Save button saves it. A row can be edited when Ligantic can tell which Record it is.

Endpoint - Respond

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.

Entity Context

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).

Experience Blocks Reference

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

Experience - Build URL

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.

Experience - Pdf - Create

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.

Experiences Reference Overview

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

Experience States and Print Layout

Block states entries are optional and support three id classes:

File - JSON Parse

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.

File - XLSX Read

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.

File - ZIP Create

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.

File - ZIP Extract

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.

Flow - Cancel

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.

Flow - Execute

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.

Flow Node Types Reference

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.

Flow - Result

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.

Flow Schedules

A schedule runs a Flow on a cadence, such as every 5 minutes, every weekday at 09:00, or 5 minutes after the previous run finishes. A Flow can have any number of schedules. Each run is a normal run of the Flow: it appears in the Flow's runs, uses credits, and logs the same way as a run started any other way.

Flow - Trigger

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.

Generated CLI commands

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>".

How to Add Aggregate Columns to a Schema View

This guide shows you how to add a column that summarises each Record's related Records, such as the number of items in each release or the total points of its items, to a Schema view or to the Schema's Records table.

How to Authenticate Requests with a JWT

This guide shows you how to let an external system call a Space's App (for example, an Endpoint, see How to Create an Endpoint) with a bearer JWT issued by its own identity provider.

How to Build Schemas, Flows, and Experiences Incrementally with the CLI

This guide shows you how to change one Schema field, Flow node or edge, or Experience block at a time, instead of sending a whole configuration.

How to Change the Direction of a Flow

This guide shows you how to lay a Flow out left to right instead of top to bottom, turn some of its nodes the other way, and choose the direction new Flows start in.

How to Chart Grouped Records

This guide shows you how to make a Bar Chart or Word Cloud show counts or totals of Records per group, such as Tasks per status or per month, without loading every Record into the page.

How to Check Whether Canvas Is Available in a Space

This guide shows you how to tell whether Canvas is available in a Space, and what to do when it is not.

How to Configure a Space for Public Access

This guide shows you how to configure a Ligantic Space so that its Experiences can be accessed by the public (unauthenticated users).

How to Convert a Canvas Literal Into a Resource

This guide shows you how to promote a literal node on a Canvas into a first-class Schema or Experience.

How to Create an Endpoint

This guide shows you how to expose a published Flow at a custom HTTP method and path (see Custom Endpoints).

How to Create a Schema

This guide shows you how to create a Schema in Studio.

How to Edit and Group Several Blocks at Once

This guide shows you how to select more than one block in the Experience designer, change their shared styles in one go, and wrap them in a new Box block.

How to Export an Experience as a PDF

This guide shows you how to style an Experience for print, generate a PDF in a Flow, and return that PDF to the user as a browser download.

How to Get Content Onto a Canvas

This guide shows you how to bring a file onto a Canvas and turn it into structured content.

How to Group a Schema View

This guide shows you how to show a Schema's Records as groups, for example tasks by status, by month, or by the project they are linked to, with a count and totals for each group.

How to Handle Pagination

List endpoints in the Ligantic API are paginated. You control limit, offset, and cursor directly.

How to Manage Space Integrations

This guide shows you how to reach the Space integrations settings area and how the available integration sections are exposed in the UI.

How to Open the Relationship Map for a Space

This guide shows you how to open the relationship map, which shows the Records in a Space and how they link to each other.

How to Publish an Experience to the Public

This guide shows you how to publish an Experience in Ligantic so that it's publicly accessible to end-users.

How to Redirect and Set Cookies from an Endpoint

This guide shows you how to let a Flow decide an Endpoint's response (see Custom Endpoints): redirect the caller, set cookies, or return a status other than the Endpoint's fixed one.

How to Run a Flow from CI

This guide shows you how to trigger a Flow from a non-interactive job (a CI pipeline, a cron job, a serverless function) and wait for it to finish, using either the SDK or the CLI.

How to Save a Flow That Has Broken Connections

This guide shows you what to do when the Flow editor says some connections can't be saved.

How to Show Records With Their Linked Records and Totals

This guide shows you how to make a block query return rows of chosen fields, totals and linked Records, read in one request: for example, every Stage in its order, with the total value of its Opportunities and the Opportunities themselves listed under it.

How to Sync Records with the CLI

This guide shows you how to create and inspect Records from the command line. A Record is an instance of a Schema — the business data a Space holds.

How to Use Generated Content on a Canvas

This guide shows you how generated content on a Canvas is accepted, and what you can and cannot do with it.

How to Use the CLI in a Script

This guide shows you how to drive ligantic from a non-interactive script or CI job: provide the API key without a prompt, select a Space, and consume JSON output.

Image

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

Input

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

Integration - HTTP

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.

Integration - SMTP

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.

Integration - SQL Connect

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.

Integration - SQL Disconnect

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.

Integration - SQL Query

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.

Link

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.

List - Aggregate

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.

List - Filter

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

List - Map

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.

Media - Audio Process

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.

Media - Video - Audio - Extract

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

Object - Create

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

Object - Link

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.

Object - Pack

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.

Object - Pick

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.

Object - Query

Queries the Records of a Schema that match a filter, with pagination and ordering. Returns the matching Records with their metadata, or, with a select/groupBy shape, rows of chosen fields, aggregates over relationships, and grouped counts and totals. Use this node to retrieve data for processing, display, or downstream operations.

Object - Query Link

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.

Object - Remove

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.

Object - Unlink

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.

Object - Update

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

Record Queries

A Record query returns a page of the Records of one Schema, shaped by an ordered select: each returned row is an object with one key per select entry, in select order. A select entry is a field of the Record, an aggregate (count, sum, avg, min or max) over the Records linked to it through a relationship, a sample of those linked Records (see Records), or an object that nests other entries (see Object).

Schema Field Types Reference

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.

SDK and CLI Reference Overview

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.

SDK API Reference

@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).

Secret - Get

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.

Secret - Remove

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.

Secret - Set

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.

Secret - Unwrap

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.

Stream - Collect

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.

Text

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

Text - Content to Text

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.

Text - Extract List Items

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.

Text HTML Query and Transform

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.

Text - Parse Document to Content

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

Text - Parse HTML to Content

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.

Text - Parse Markdown to 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.

Text - Recursive Split

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.

Text - Template

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 Record Query Shape

A Record query asks for a page of the Records of one Schema, or of groups of them, and says, in one ordered list, exactly what each returned row contains. "Appointments per month, with how many are pending and the first three of them" is one query:

The Result-Based Error Model

This explains why the SDK never throws, what a Result is, and how to read a LiganticError.

The SDK as an API Mirror

This explains the compatibility model: how the SDK relates to the Ligantic OpenAPI contract, what it mirrors, and how versions move.

UX - Action

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.

UX - Message

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.

Video

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

Visualisation

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

Your First Integration with the Ligantic SDK

This tutorial walks you through your first end-to-end integration with the Ligantic SDK: install the package, authenticate with an API key, list a Space, read a Record, and run a Flow.

Your First Task Tracker

Build a task list in Studio without writing code. You will create a Schema, add two Records and update a task.