Clients
The two entry-point classes — pick the one that matches your runtime.
Convilyn (sync)
from convilyn import Convilyn
client = Convilyn(api_key="ck_...") # or read from CONVILYN_API_KEY env
A blocking, synchronous client suitable for scripts and shells. Wraps AsyncConvilyn internally — calling a sync method blocks the current thread on the async implementation.
Constructor parameters
| Name | Type | Default | Notes |
|---|---|---|---|
api_key | str | None | None | Reads CONVILYN_API_KEY env var if unset |
base_url | str | None | None | Reads CONVILYN_BASE_URL env var; defaults to https://api.convilyn.com |
ws_url | str | None | None | WebSocket URL for goal-lane event streams. Optional for non-goals workflows. |
timeout | float | 30.0 | Default HTTP timeout in seconds |
retry_policy | RetryPolicy | None | ExponentialBackoffRetry(...) | Pass a custom retry policy, or NoRetry() to disable |
Resource accessors
client.files # Files — upload / register
client.convert # Convert — turbo-lane document conversion jobs
client.goals # Goals — goal-lane (multi-step) workflow jobs
client.workflows # Workflows — community marketplace (search / fork / publish / like)
client.account # Account — billing tier + cost-preview / quota queries
Context manager support
with Convilyn() as client:
file = client.files.upload("doc.pdf")
# ... HTTP connections closed on exit
Methods
close()— release the underlying HTTP client. Use the context manager form when possible.
AsyncConvilyn (async)
from convilyn import AsyncConvilyn
async with AsyncConvilyn() as client: # reads CONVILYN_API_KEY from env
file = await client.files.upload("doc.pdf")
The native async variant. Every resource method has an async counterpart with the same signature as the sync version.
Constructor parameters
Same as Convilyn above.
Resource accessors
client.files # AsyncFiles
client.convert # AsyncConvert
client.goals # AsyncGoals (incl. `goals.events(...)` WS streaming — async only)
client.workflows # AsyncWorkflows
client.account # AsyncAccount
goals.events(job_spec_id) is the one method that's async-only — it returns an AsyncIterator[GoalEvent] over the WebSocket stream. The sync Convilyn does NOT expose it because bridging a WebSocket through asyncio.run per call is ergonomically wrong; switch to AsyncConvilyn when you need streaming.
Async context manager
async with AsyncConvilyn() as client:
file = await client.files.upload("doc.pdf")
# ... connections closed on exit
Methods
aclose()— async cleanup of the underlying HTTP client.
Choosing between them
- Use
Convilynfor scripts, REPL sessions, one-shot CLI usage. - Use
AsyncConvilynwhen you're already inside an event loop (FastAPI, Starlette, an async worker, etc.). It avoids the overhead of synchronously bridging throughasyncio.run.
Both share the same retry policy, transport configuration, and error types — switching between them is mechanical.