SDKs

Official Flowra SDKs wrap the public API-key surface (the same operations as the API reference). Use them from your backend instead of hand-writing HTTP for common flows. Source: github.com/flowradev/sdk.

Package	Language	Notes
`@flowra/sdk`	TypeScript / Node 18+	OpenAPI-generated client + product facade
`flowra-sdk`	Python 3.10+	Hand-written facade (stdlib HTTP, no extra deps). Import stays `flowra`.
`@flowra/cli`	Terminal	Discover → connect → execute when MCP is not connected

When to use the SDK vs MCP vs CLI vs curl

Approach	Use when
SDK	Your app/backend calls Flowra (list tools, run workflows, manage skills, knowledge, MCP servers, …)
MCP	An IDE or agent runtime (Cursor, Claude Desktop) should discover and call tools. Prefer OAuth (URL only); API key is the fallback — see MCP
CLI	A terminal agent can run shell commands and MCP is not connected (`flowra discover` → `connect` → `execute`)
HTTP / curl	Quick checks, languages without an SDK yet — Quickstart and API reference

The SDKs are not a Composio-style agent framework. For agent-side tool access, prefer MCP.

Install

TypeScript — @flowra/sdk on npm

npm install @flowra/sdk
# or: pnpm add @flowra/sdk

From the SDK repo (optional): pnpm --dir typescript install && pnpm --dir typescript build. Python PyPI name is flowra-sdk. Import stays flowra. Do not pip install flowra — that name is an unrelated package.

pip install flowra-sdk

Requires Python 3.10+. Stdlib only (no extra runtime deps). From the SDK repo: pip install -e "./python". CLI — @flowra/cli on npm

pnpm add -g @flowra/cli
flowra --help

Authenticate

Both clients send your project API key as x-api-key. Optionally set an external user with username / x-username for multi-tenancy.

import { Flowra } from '@flowra/sdk';

const flowra = new Flowra({
  apiKey: process.env.FLOWRA_API_KEY!,
  // username: 'customer_alice',
});

from flowra import Flowra
import os

flowra = Flowra(
    api_key=os.environ["FLOWRA_API_KEY"],
    # username="customer_alice",
)

Create keys in the dashboard — Authentication · Projects and API keys.

Common examples

Copy tool slugs from tools.list (or DISCOVER). Do not invent them. Catalog actions are typically UPPER_SNAKE (GMAIL_SEND_EMAIL, SLACK_SEND_MESSAGE).

List tools and execute one

const tools = await flowra.tools.list({ limit: 10, toolkitSlug: 'slack' });
const slug = tools.data?.[0]?.slug ?? tools.items?.[0]?.slug ?? 'SLACK_SEND_MESSAGE';
await flowra.tools.execute(slug, {
  arguments: { channel: '#general', text: 'Hi' },
});

tools = flowra.tools.list(limit=10, toolkitSlug="slack")
items = tools.get("data") or tools.get("items") or []
slug = (items[0] or {}).get("slug", "SLACK_SEND_MESSAGE") if items else "SLACK_SEND_MESSAGE"
flowra.tools.execute(
    slug,
    {"arguments": {"channel": "#general", "text": "Hi"}},
)

Run a workflow and poll status

const run = await flowra.workflows.run(workflowId, {
  input: { message: 'smoke test' },
  mode: 'production',
});
const status = await flowra.workflows.status(run.threadId);

run = flowra.workflows.run(workflow_id, {"input": {"message": "smoke test"}, "mode": "production"})
status = flowra.workflows.status(run["threadId"])

Act as an end user

const alice = flowra.asUser('customer_alice');
await alice.connections.createLink({
  authConfigId: 'AUTH_CONFIG_ID',
});

alice = flowra.as_user("customer_alice")
alice.connections.create_link({"authConfigId": "AUTH_CONFIG_ID"})

Create a knowledge collection and ingest a URL

const collection = await flowra.knowledge.create({ name: 'Help center' });
await flowra.knowledge.ingestUrl(collection.id, {
  url: 'https://docs.yoursite.com/faq',
});

collection = flowra.knowledge.create({"name": "Help center"})
flowra.knowledge.ingest_url(collection["id"], {"url": "https://docs.yoursite.com/faq"})

Chat stream (Python events)

thread = flowra.chat.create_thread({})
for event in flowra.chat.stream(
    thread["thread_id"],
    {"input": {"messages": [{"role": "user", "content": "Hello"}]}},
    as_events=True,
):
    print(event["event"])

More: Chat streaming · TypeScript tutorial · Python tutorial.

One shot from a terminal

When MCP isn’t connected: discover → connect → execute. Never invent the slug.

flowra login
flowra discover "Gmail list recent inbox emails"
flowra connect gmail
flowra execute GMAIL_SEND_EMAIL -d '{"recipient_email":"you@example.com","subject":"Hi","body":"Test"}'

If connect returns redirectUrl, open it, then run connect again.

Namespaces

High-level helpers cover the main product areas (camelCase in TypeScript, snake_case in Python): tools, toolkits, skills, workflows, connections, authConfigs / auth_configs, users, triggers, chat, files, knowledge, database, sandbox, mcp, llm, browser, usage Full method map: SDK namespaces. Every method with examples: SDK method examples. Credits: Usage and credits. Escape hatches:

TypeScript: flowra.raw (generated OpenAPI operations)
Python: flowra.request(method, path, ...)

Tutorials

TypeScript SDK

Full examples: tools, workflows, chat, files, sandbox, usage, raw client.

Python SDK

Full examples: tools, workflows, chat stream, files, sandbox, errors.

Chat streaming

SSE runs and usage events.

Usage and credits

Balance, ledger, workflow usage.

All method examples

TypeScript and Python snippets for every facade method.

Getting started

SDK reference

Core building blocks

Data and runtime

Integrate and scale

Recipes

Native tools

Contributing

When to use the SDK vs MCP vs CLI vs curl

Install

Authenticate

Common examples

List tools and execute one

Run a workflow and poll status

Act as an end user

Create a knowledge collection and ingest a URL

Chat stream (Python events)

One shot from a terminal

Namespaces

Tutorials

TypeScript SDK

Python SDK

Chat streaming

Usage and credits

All method examples

​When to use the SDK vs MCP vs CLI vs curl

​Install

​Authenticate

​Common examples

​List tools and execute one

​Run a workflow and poll status

​Act as an end user

​Create a knowledge collection and ingest a URL

​Chat stream (Python events)

​One shot from a terminal

​Namespaces

​Tutorials

TypeScript SDK

Python SDK

Chat streaming

Usage and credits

All method examples

​Related

When to use the SDK vs MCP vs CLI vs curl

Install

Authenticate

Common examples

List tools and execute one

Run a workflow and poll status

Act as an end user

Create a knowledge collection and ingest a URL

Chat stream (Python events)

One shot from a terminal

Namespaces

Tutorials

Related