Consumer SDK

Call Convilyn from your app.

Convert files on your own machine with no account at all, or upload them and run conversions, agentic goal workflows and the community marketplace behind a single ck_ API key. Python is the supported SDK today; TypeScript is in pre-release and Go is coming soon.

The consumer SDK is for code that uses Convilyn. Building the tools and workflows the platform runs? That's the Author SDK.

Pick your language

Every language is a faithful port of the same wire contract. Python is the supported SDK and the one every example here is written in; TypeScript is a pre-release preview and Go is coming soon.

Pythonconvilyn

Convilyn + AsyncConvilyn, Pydantic models, a convilyn CLI. uv add --prerelease=allow convilyn (or pip install --pre convilyn)

TypeScript@convilyn/sdkPre-release

Promise-based Convilyn, ESM + CJS + types, a convilyn CLI. Pre-1.0 and still moving — npm install @convilyn/sdk

Goconvilyn-consumer-goComing soon

context.Context-first client, std-lib only, errors.Is/As.

What you can do

Resource	What it does
`local`	Convert files on your own machine — no key, no account, no network (Python only)
`files`	Presigned upload → object storage → confirm, streaming large files without buffering
`convert`	Hosted conversion (DOCX / PDF / PPTX / TXT / HTML / Markdown / …)
`goals`	Agentic workflows with human-in-the-loop (`fill_slot` / `confirm`), a live event stream, and `understand()` for schema-constrained output
`workflows`	The community marketplace — search, fork, publish, like
`user_workflows`	The workflows you own — list, export, inspect recent runs, delete
`builder`	Author a workflow by chat — describe what you want, get a runnable `uw_` back (Pro tier)
`account`	Plan, cost preview, and quota — pre-flight a call before spending

One client, every resource

from convilyn import Convilyn, local
 
local                  # convert on this machine — no client, no key
 
client = Convilyn()
client.files           # uploads
client.convert         # hosted conversion
client.goals           # agentic workflows + HITL
client.workflows       # marketplace
client.user_workflows  # the workflows you own
client.builder         # author a workflow by chat
client.account         # plan & quota

TypeScript SDK is in pre-release — see its reference section. Go SDK is coming soon.

Build a workflow by chat

The Builder turns a plain-language description into a runnable workflow — the same "describe it, get a uw_" flow as the web app, now callable from your own client (desktop, edge, or a server). Create a session, send turns until the builder emits a register verdict, then hand the returned id straight to goals. Builder authoring requires a Pro-tier account.

from convilyn import Convilyn
 
client = Convilyn()
session = client.builder.create_session()
 
turn = client.builder.send_message(session.chat_id, "Summarise a PDF and email the highlights")
while turn.verdict_action == "request_input":
    # answer turn.pending_slots however your UI collects input
    turn = client.builder.send_message(session.chat_id, "Weekly, to me")
 
if turn.verdict_action == "register":
    workflow_id = turn.registered_workflow_id       # the built uw_
    job = client.goals.run(workflow_id=workflow_id, files=[file_id])

TypeScript SDK is in pre-release — see its reference section.

Free-tier callers get a 402 TIER_REQUIRED (PlanRequiredError in Python). Check your remaining turns with client.builder.quota().

Reference

Python reference

Clients · Exceptions · Types

TypeScript referencePre-release

Client · Resources · Errors · CLI

Go referenceComing soon

Client · Resources · Errors

Need an endpoint the SDK doesn't wrap?

The convilyn CLI ships a gh-style api sub-command that calls any endpoint with the same auth, retry, and idempotency behaviour as the high-level methods. See the Quickstart.