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).
Note: Constructing
new Ligantic({ apiKey })validatesapiKeyand throws if it is missing/empty.
- Package:
@ligantic/sdk - Requires Node.js 22+
- Entry point:
import { Ligantic } from "@ligantic/sdk"
The Ligantic Client
new Ligantic(options: LiganticOptions)The client owns authentication, the User-Agent header, the base URL, and the retry-aware transport. It exposes five resource groups: identity, spaces, schemas, records, and flows.
LiganticOptions
Field | Type | Default | Description |
|---|---|---|---|
|
| — (required) | Sent as |
|
|
| Override for staging or self-hosted deployments. |
|
|
| Retry policy. See Retry. |
|
| global | Injectable for tests. |
|
|
| The |
Instance Properties
Property | Type | Description |
|---|---|---|
|
| The authenticated user. |
|
| Spaces: list, get, create, rename, delete. |
|
| Schemas: list, get, create, update, delete, get config. |
|
| Records: list, query, get, create, update, delete, json-patch. |
|
| Flows: CRUD, run, and run inspection. |
|
| Experiences: list, get, create, rename, delete, clone. |
client.request(method, path, options?)
The transport boundary. Performs a single, retry-aware request and returns the parsed JSON body as a LiganticResult<TransportResult>. Applies authentication, the User-Agent, and the retry policy, and normalises failures into a LiganticError. It never throws.
request(
method: string,
path: string,
options?: {
query?: Record<string, unknown>;
body?: unknown;
signal?: AbortSignal;
},
): Promise<LiganticResult<TransportResult>>TransportResult is { status: number; headers: Headers; body: unknown }.
Exported Constants
Constant | Value | Description |
|---|---|---|
|
| The SDK version, sent in |
|
| The default base URL. |
Result and Error Types
Result<T, E>
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
type LiganticResult<T> = Result<T, LiganticError>;Helpers: ok(value), err(error), and tryOr(fn, toError) (captures a thrown error as the Err side).
See The Result-Based Error Model.
LiganticError
The Err side of every result. Mirrors the API error envelope { message, code, issues? } and adds the HTTP status and requestId.
Field | Type | Description |
|---|---|---|
|
| Human-readable message. |
|
| HTTP status, or |
|
| The API error code, for example, |
|
| Validation issues, present for |
|
| The |
|
| The |
|
| True when |
|
| True for transport errors, |
transportError(cause) normalises a thrown fetch failure: aborted requests become REQUEST_ABORTED, other failures become NETWORK_ERROR.
Retry
RetryOptions controls the retry policy.
Field | Type | Default | Description |
|---|---|---|---|
|
|
| Max retries, not counting the initial attempt. |
|
|
| Base backoff delay. |
|
|
| Upper bound on a single backoff delay. |
|
|
| Upper bound on a single |
|
|
| Methods considered idempotent. |
|
|
| Injectable clock for tests. |
|
|
| Injectable jitter source (0..1). |
|
| — | Called before each retry with |
A 429 is always auto-retried, for any method — the server rejects it before the handler runs, so it is safe even for POST and PATCH. Other retryable failures (transport failures, 408, 5xx) are retried only for idempotent requests (GET, DELETE, PUT). Backoff is exponential with full jitter; a 429 with a Retry-After waits at least that long, capped by maxRetryAfterMs.
Identity
Method | Signature | Returns |
|---|---|---|
|
|
|
GET /users/me — the authenticated user for the current API key.
Spaces
Method | Signature | Returns |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
list—GET /spaces. Returns a summary per Space (id,title,role, owner info).get—GET /spaces/{spaceId}.create—POST /spaces.CreateSpaceInputis{ title, parentSpaceId?, organisationId?, organisationBillingAccountId?, cloneFromSpaceId? }. Returns{ spaceId }.rename—PATCH /spaces/{spaceId}/title. Updates the Space title.delete—DELETE /spaces/{spaceId}.
Schemas
Method | Signature | Returns |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
list—GET /spaces/{spaceId}/schemas.get—GET /spaces/{spaceId}/schemas/{schemaId}. Includes the Schema's versions.create—POST /spaces/{spaceId}/schemas.update—PATCH /spaces/{spaceId}/schemas/{schemaId}. Updates name, display template, auto-save, and config.delete—DELETE /spaces/{spaceId}/schemas/{schemaId}.getConfig—GET /spaces/{spaceId}/schemas/{schemaId}/config.
Records
A Record is an instance of a Schema. Its API paths use entities; the SDK exposes it as records.
Method | Signature | Returns |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
list—GET /spaces/{spaceId}/schemas/{schemaId}/entities. Params are passed through raw:limit,offset,cursor,filter,sort,select,fullTextFilter, and more. Returns{ entities, count, offset, limit }.query—POST /spaces/{spaceId}/schemas/{schemaId}/entities/query. Runs a Record query.QueryRecordsInputis{ select, groupBy?, filter?, sort?, offset?, limit?, cursor? };limitabove 1000 is lowered to 1000. Returns{ rows, count, offset, limit }, one row per Record (or per group withgroupBy), keyed by select alias.get—GET /spaces/{spaceId}/schemas/{schemaId}/entities/{entityId}.create—POST .../entities.CreateRecordInputis{ data?, hasPendingUploads?, nameBased? }. Returns{ entityId }.update—PATCH .../entities/{entityId}. Full replace of the data object.delete—DELETE .../entities/{entityId}.patch—PATCH .../entities/{entityId}/json-patch. Applies a JSON Patch.JsonPatchInputis{ operations: JsonPatchOperation[], hasPendingUploads?, nameBased? }where each operation is one ofadd,remove,replace,move,copy, ortest. Anaddorreplaceof a field inside an object the Record does not have, or holds asnull(for example/price/currencyon a Record without a price), adds the object with that field.createRelationship—POST /spaces/{spaceId}/schemas-relationships/{schemaRelationshipVersionId}/entities. Creates a relationship (link) row between two Records for a Schema relationship version.inputis{ fromId, toId }(the Record IDs on the version's from/to sides). Returns{ entityRelationshipId }. A relationship version whose field is nested inside an array is rejected with aBAD_REQUEST— the link names no array row. Set such a field with a row-levelupdate/patchon the specific array row instead.removeRelationship—DELETE /spaces/{spaceId}/schemas-relationships/{schemaRelationshipVersionId}/entities/{entityRelationshipId}. Removes a relationship (link) row. TheentityRelationshipIdis theidof a relationship row (seeget/listwith relationships).getFileUrl—GET /spaces/{spaceId}/schemas/{schemaId}/entities/{entityId}/files/{fileId}. Returns a short-lived signed URL for a file attached to the Record. Fetch the URL with a plainGET(no API key) to download the bytes. Needs read access to the Record; a file that is not on the Record returnsNOT_FOUND. File IDs are theidof the file entries in the Record's data (f-…).prepareFile—POST /spaces/{spaceId}/schemas/{schemaId}/files. Builds a file entry for a top-level file field, or for media embedded in a top-level content field, without writing anything.PrepareFileInputis{ field, name, size, mimeTypeId? }.fieldis the field's name or id.mimeTypeIddefaults to the type forname's extension. The server checkscreateorupdateaccess. For a file field, it checks the field's allowed types and maximum size. For a content field, the file must be an image, video or audio file whose block type the field allows; there is no size limit, as in the app's content editor. The block follows the file type. A.webmname is typedaudio/webm, so passmimeTypeId: "video/webm"for a video; the genericwebmtype fits both and uses video where the field allows it, otherwise audio. A failed check returnsBAD_REQUESTwith the reason. Returns{ file, fieldId, fieldName, multiple, contentBlock? }.fileis a plain file entry:hasPendingUploadsgoes on the write request, not on the entry.contentBlockis set for a content field and names the block type (image,videooraudio) to embed the file in.createFileUploadUrl—POST /spaces/{spaceId}/schemas/{schemaId}/entities/{entityId}/files/{fileId}. Returns{ uploadUrl, uploadFields }, a short-lived signed upload for a file entry already in the Record's data.NOT_FOUNDif the entry is not there.confirmUploads—POST .../entities/{entityId}/confirm-uploads-complete. Runs the Record'screateorupdateFlows thathasPendingUploadsdeferred.
Upload files the way the app does, so that required file fields are satisfied and Flows see the files:
- Call
prepareFilefor each file. - Write each
fileinto its field withcreate,updateorpatch, passinghasPendingUploads: trueon that request. For a multiple-file field, write a list. For a content field, add a block{ "type": contentBlock, "src": file, "children": [{ "text": "" }] }to the field's content. - For each file, call
createFileUploadUrl, thenPOSTamultipart/form-databody touploadUrlwith everyuploadFieldsentry, then the bytes as the last field,file. Send no API key. The body must be exactlysizebytes, and the signed upload expires after a few minutes. - Call
confirmUploadswith"create"or"update". Skip this step if an upload failed, so that Flows do not run without the file.
A Record from get or list and the result of update or patch include its version. It is 1 when the Record is created and increases by one with every write to it (including archiving and restoring), in the order the writes are applied, so of two reads of the same Record the one with the higher version is the newer. Adding or removing a Record's relationships does not change it.
Flows
run runs the current published Flow. The SDK cannot select a Flow version.
Method | Signature | Returns |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
list—GET /spaces/{spaceId}/flows.get—GET /spaces/{spaceId}/flows/{flowId}. Includes the Flow's versions.create—POST /spaces/{spaceId}/flows.delete—DELETE /spaces/{spaceId}/flows/{flowId}.getBySchema—GET /spaces/{spaceId}/flows/by-schema/{schemaId}.run—POST /spaces/{spaceId}/flows/{flowId}/execute. Asynchronous: returns{ flowExecutionId, spaceId }immediately.RunFlowInputis{ triggerNodeId?, inputs?, hasPendingUploadFiles?, nameBased?, logLevel?, scheduledAt? }.listRuns—GET /spaces/{spaceId}/flows/{flowId}/executions. Returns{ total, limit, offset, data }.getRun—GET .../executions/{executionId}.getRunOutputs—GET .../executions/{executionId}/outputs. Returns the run plus itsoutputs(a map of output handle name → value, ornull).cancelRun—POST .../executions/{executionId}/cancel.
FlowRunStatus
"scheduled" | "pending" | "executing" | "failed" | "succeeded" | "cancelled". The terminal statuses are succeeded, failed, and cancelled.
Experiences
Method | Signature | Returns |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
list—GET /spaces/{spaceId}/experiences.ListExperiencesParamsis{ omitUnpublished?, omitExperiencesWithRequiredPathVariables? }. Each summary is{ id, name, pathname, isPublished }.get—GET /spaces/{spaceId}/experiences/{experienceId}. Returns the latest version, or the version given byexperienceVersionId, including itsblockandmetadata. Fails with aNOT_FOUNDerror when the Experience does not exist.create—POST /spaces/{spaceId}/experiences.CreateExperienceInputis{ name, title?, pathname? }. Creates a draft first version and returns{ experienceId, experienceVersionId }.rename—PATCH /spaces/{spaceId}/experiences/{experienceId}.delete—DELETE /spaces/{spaceId}/experiences/{experienceId}.clone—POST /spaces/{spaceId}/experiences/{experienceId}/clone.CloneExperienceInputis{ experienceVersionId? }.listVersions—GET /spaces/{spaceId}/experiences/{experienceId}/versions. Newest first.ListExperienceVersionsParamsis{ limit?, cursor? }; pass the returnednextCursorback ascursorwhilehasMoreis true.createVersion—POST .../versions. Creates a draft version.CreateExperienceVersionInputis{ title, pathname, poweredByLogoRemoved, block?, version?, sourceExperienceVersionId? };versiondefaults to the latest version with its patch number incremented, andsourceExperienceVersionIdcopies that version's metadata.updateVersion—PATCH .../versions/{experienceVersionId}.UpdateExperienceVersionInputis{ title, pathname? }.setVersionContent—PUT .../versions/{experienceVersionId}/content. Replaces the version's root block. Only draft versions can be changed; a published version fails withNOT_FOUND.publishVersion—POST .../versions/{experienceVersionId}/publish.setVersionMetadata—PUT .../versions/{experienceVersionId}/metadata/{name}. Creates or replaces a page metadata value such asdescription,og:title, orog:image.ExperienceMetadataValueis a string, or a media source for image and icon names. Works on draft and published versions.renameVersionMetadata—POST .../metadata/{currentName}/rename. Moves the value tonewName, replacing any value already set there. Fails withNOT_FOUNDwhencurrentNameis not set.removeVersionMetadata—DELETE .../metadata/{name}.
Read a version's metadata from the metadata field of get.
A published Experience changes only through a draft version: createVersion creates the draft, setVersionContent sets its content, and publishVersion publishes it. Read a version's content with get(spaceId, experienceId, { experienceVersionId }).
Exported Types
The package re-exports the stable public types: User, Space, SpaceSummary, CreateSpaceInput, CreateSpaceResult, UpdateSpaceTitleInput, Schema, SchemaSummary, CreateSchemaInput, CreateSchemaResult, UpdateSchemaInput, UpdateSchemaResult, SchemaConfig, LiganticRecord, ListRecordsResult, ListRecordsParams, QueryRecordsInput, QueryRecordsResult, CreateRecordInput, CreateRecordResult, UpdateRecordInput, UpdateRecordResult, JsonPatchInput, JsonPatchOperation, JsonPatchResult, Flow, FlowSummary, CreateFlowInput, CreateFlowResult, ListFlowsParams, ListFlowsBySchemaParams, RunFlowInput, RunFlowResult, FlowRun, FlowRunStatus, ListRunsParams, ListRunsResult, RunOutputs, GetRunOutputsParams, Experience, ExperienceSummary, GetExperienceParams, ListExperiencesParams, CreateExperienceInput, CreateExperienceResult, CloneExperienceInput, CloneExperienceResult, ExperienceVersionSummary, ListExperienceVersionsParams, ListExperienceVersionsResult, CreateExperienceVersionInput, CreateExperienceVersionResult, UpdateExperienceVersionInput, ExperienceBlock, ExperienceMetadataName, ExperienceMetadataValue, plus the result/error types and the resource classes (Identity, Spaces, Schemas, Records, Flows, Experiences).