Convilyn developers

Developers

The Convilyn developer documentation — Python SDK, REST API, and everything an integration needs.

This section is English only. Endpoint paths, parameter names, and Python symbols are themselves English; translating them would only add risk of drift. For end-user product documentation in your language, switch to the user manual.

What Convilyn offers

SurfaceAudienceInstallCLI
convilynAPI callers — apps, agents, scripts that use Convilynpip install convilynconvilyn
convilyn-sdkWorkflow authors — third parties who build tool servers and workflow specs for Convilynpip install convilyn-sdkconvilyn-author
REST APIDirect HTTP integration——

The two Python packages are intentionally separate so the consumer SDK stays lightweight — applications that only call the API don't pull in the server-side dependencies that workflow authors need.

Start here

  • Quickstart — pip install to first conversion in under five minutes
  • Consumer SDK Reference — Convilyn, AsyncConvilyn, exceptions, and the Pydantic data models (for API callers)
  • Author SDK Reference — ToolServer, WorkflowSpec, policies, and the multi-role primitives (for workflow authors)
  • REST API — the OpenAPI 3.1 contracts behind the SDK

Requirements

  • Python 3.10 or later
  • A Convilyn API key (ck_...) created in your Settings → API page — the page is auth-gated and is also where you manage billing and quota
  • For authors: an HTTPS-reachable endpoint to host your tool server (Lambda, Fargate, or any VM)

Production-grade defaults

The consumer SDK ships with sensible defaults so you don't have to wire them yourself:

  • Retry on 5xx / 429 / 408 with exponential backoff and jitter
  • Idempotency-Key auto-stamped on every mutating verb; Retry-After honoured
  • Typed billing exceptions — PlanRequiredError, QuotaExceededError — so callers can distinguish "wrong plan" from a transient backend error
  • PEP 561 typed (py.typed marker); mypy / pyright / pylance pick up the hints automatically
  • --json output, --dry-run previews, and pinned exit codes on every CLI command