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.

The Core Idea

The SDK is a versioned mirror of the OpenAPI v1 surface. It is not an independent API with its own semantics — it is a faithful, typed projection of the REST contract that Ligantic already exposes at /api/v1/*.

• The types follow the API contract, so they stay in step with it.
• The names and calling style are stable. The SDK gives the API's shapes readable names (Space, Schema, LiganticRecord, Flow, FlowRun) and a result-based, never-throw API.

The SDK does not invent endpoints the API doesn't have.

What the Mirror Means in Practice

• Additive API surface → SDK minor. When the API adds an endpoint or field that the SDK can expose without breaking existing code, the SDK adds it in a minor release.
• The SDK majors on its own breakage. If the SDK changes its public surface in a breaking way (a renamed method, a changed result shape), that is a major SDK release — independent of the API's own versioning.
• No hidden behavior. The SDK does not cache, mutate, or reinterpret API responses. What the API returns is what the Result carries (as a typed value).

Query Parameters

List methods take structured query parameters (filter, sort, select, …) as plain objects and arrays. The SDK sends them to the server as you pass them.

What the v1 Mirror Covers

The v1 capability matrix:

• Identity — me.
• Spaces — list, get, create, rename, delete.
• Schemas — list, get, create, update, delete, get config.
• Records — list, get, create, update, delete, json-patch, createRelationship, removeRelationship.
• Flows — list, get, create, delete, get-by-schema, run, and run inspection (list, get, outputs, cancel).

Not covered by v1: Experiences, Flow versions and version-pinned runs, organisations, membership, export/import, folders, billing, and updating relationships. v1 runs the current published version of a Flow.

Deprecation and Removal

The SDK follows a deprecate-then-remove policy:

1. A member is marked @deprecated in JSDoc in the next minor, with the replacement named.
2. The deprecated member stays functional for at least one minor (and through the current major for API-driven deprecations).
3. Removal happens only in a major, and is listed in the release notes.

The CLI applies the same policy: a deprecated command or flag prints a warning to stderr that does not affect --json stdout.

Lockstep with the CLI

The SDK and CLI are released in lockstep with a shared SemVer. The CLI is built on the SDK and the two are one developer experience, so a breaking SDK change and the CLI change that follows from it ship together in the same major.