SDKs - Orkestia Documentation

SDKs

Typed clients for Orkestia — Node and Python workflow SDKs, plus the browser OAuth SDK for Sign in with Orkestia

Orkestia is the same catalog and the same engine no matter how you call it. The SDKs are the typed way to drive that catalog from application code. MCP is the agent-facing surface; REST is the language-agnostic one. Pick the driver that matches the caller.

Workflows — Node / TypeScript

@ltinteg/workflows-sdk — one typed binding per workflow, SSE streaming, run.wait(). The most complete client.

Workflows — Python

ltinteg-workflows-sdk — Pydantic-typed start helpers over the same REST surface.

Auth — Sign in with Orkestia

@orkestia/auth — browser PKCE / OAuth SDK for your app's end-users. No secret in the client.

Which SDK do I install?

You are…	Install	Then
Calling workflows from Node or TypeScript	`@ltinteg/workflows-sdk`	`new LtIntegWorkflowsClient({ baseUrl, token })`
Calling workflows from Python	`ltinteg-workflows-sdk`	`LtIntegWorkflowsClient(base_url, token=…)`
Adding login to an app you built on Orkestia	`@orkestia/auth`	`createOrkestiaAuth({ clientKey })`
Sending exceptions to Lumen from Python	`orkestia-lumen-sdk`	See Send data
An AI agent	none — use MCP	`list_workflow_types` → `start_workflow`

The workflow SDKs are generated from the same live catalog as reference.orkestia.dev. Per-workflow input and output types come from that catalog — do not hard-code shapes from examples on this site.

Two tokens, two jobs

The workflow SDKs accept either token. The auth SDK mints the end-user one.

Token	Who holds it	How you get it	What a run can touch
Org-member	Your team, CI, an MCP agent	Org login or an API token from Settings → API tokens	The whole organization's resources
End-user	A user of your app	`@orkestia/auth` PKCE flow	Only that user's data, and only workflows you exposed

Both are sent as Authorization: Bearer …. The organization is resolved server-side — never pass organization_uuid in initial_data unless a workflow schema explicitly requires it.

// Org automation (Node)
const client = new LtIntegWorkflowsClient({
  baseUrl: "https://workflow-api.orkestia.dev",
  token: process.env.ORKESTIA_TOKEN,
})

// Acting as a signed-in app user (same client, different token)
const endUserClient = new LtIntegWorkflowsClient({
  baseUrl: "https://workflow-api.orkestia.dev",
  token: session.token, // from @orkestia/auth
})

See Identity & multi-tenancy for the two identity planes.

The loop is the same

discover types  →  get schema  →  start a run  →  watch / wait  →  (retry)

Node, Python, REST, and MCP all wrap that loop. A run you start from the Node SDK is the same workflow_id you can stream over REST or inspect from an agent.

How are you calling Orkestia?
Node / TS SDK
Python SDK
@orkestia/auth
end-user login
REST
MCP
Same engine, same runs

How are you calling Orkestia?→ app / service in Node →Node / TS SDK
How are you calling Orkestia?→ app / service in Python →Python SDK
How are you calling Orkestia?→ browser login for your users →@orkestia/auth
How are you calling Orkestia?→ any other language →REST
How are you calling Orkestia?→ AI agent →MCP
@orkestia/auth→ end-user JWT →Node / TS SDK
Node / TS SDK→Same engine, same runs
Python SDK→Same engine, same runs
REST→Same engine, same runs
MCP→Same engine, same runs

Where to go next

Quick start

First run from the dashboard, an SDK, or MCP.

API & tooling

REST endpoints the SDKs wrap, plus the two-token auth model.

App Enablement

Provision an identity app, then wire @orkestia/auth.

Live catalog

Exact workflow names, inputs, and outputs.

Query API

Read and mutate Lumen over HTTP — logs, error groups, traces, metrics, Pulse, dashboards, and rule JSON

Workflows SDK — Node / TypeScript

Typed ESM client for every Orkestia workflow — one autocompleted binding per type, SSE streaming, and wait-for-terminal