Official SDKs for Writ, your own API to any website. Each one has a client for Writ Desktop on your own computer (run saved workflows and APIs, follow their live run events, read the data they collect, manage monitors, automations, personas, secrets and files) and a client for Writ Cloud (scrape a page to clean markdown, map a site, run a crawl, save a crawl and call it again, follow monitors).
All four SDKs implement the same specification, so an example translates almost line for line between them.
| Language | Package | Install |
|---|---|---|
| TypeScript | @usewrit/agent-sdk |
npm i @usewrit/agent-sdk |
| Python | writ-agent |
pip install writ-agent |
| Go | github.com/usewrit/writ-sdks/go |
go get github.com/usewrit/writ-sdks/go |
| Rust | writ-client |
cargo add writ-client |
Requirements: Node ≥18 · Python ≥3.10 · Go ≥1.23 · Rust stable.
Other languages: codegen/ generates raw REST bindings for Java, C#,
Ruby and PHP from the OpenAPI spec. Those are unsupported and lack discovery and
run_and_wait — see DESIGN.md §4/§8 to port those helpers.
Three more packages let a website run Writ workflows on its visitors' own computers, through the Writ browser extension, with Writ Cloud as the fallback:
| Package | Purpose | Install |
|---|---|---|
@usewrit/web (web/) |
The page side: talks to the Writ browser extension (setup banner, installable workflows, typed calls) | npm i @usewrit/web |
@usewrit/server (server-node/) |
Verify signed receipts and run the Writ Bridge from a Node server | npm i @usewrit/server |
usewrit (usewrit-python/) |
The same for Python servers, with FastAPI integration | pip install usewrit |
Requirements: any current browser for @usewrit/web (Node ≥18 only to build and test it) ·
Node ≥18 · Python ≥3.10.
The same client covers both. Use either, or both from the same process.
| Target | What it is | How you point at it |
|---|---|---|
| Writ Desktop | Writ Desktop on your own computer, through its engine writ-agentd, over loopback |
automatic discovery, nothing to configure |
| Writ Cloud | the hosted service at usewrit.app | set WRIT_API_KEY |
The default. The client finds the running engine and its token by itself
(127.0.0.1:8131, HTTPS twin on :8132). Nothing leaves the machine. This is
where workflows, runs with live SSE events, data, monitors, selectors and
extractors, automations, personas, secrets, files and API keys live.
writ = WritAgent() # discovers Writ Desktop on this computer
writ.workflows.list()Set WRIT_API_KEY and the .cloud namespace runs on Writ Cloud: scrape,
map, crawl / crawl_status, monitors (including run and watch),
automations and personas.
export WRIT_API_KEY=wt_... # usewrit.app → Developers → API KeysWithout a key, cloud calls fall back to a free daily-capped keyless tier.
Keyless calls send a persistent id. Enforcing a free daily cap requires recognising the caller across runs, so the first keyless cloud call mints a random id at
~/.writ/client_idand sends it thereafter. Local usage and keyed usage never create it. Details and how to reset it:SECURITY.md.
Every snippet below does the same two things: talk to Writ Desktop (discovered automatically), then run a call against Writ Cloud.
TypeScript
import { WritAgent } from "@usewrit/agent-sdk";
// 1. Writ Desktop: discovers the running engine and its token.
const writ = await WritAgent.discover();
const workflows = await writ.workflows.list();
const run = await writ.workflows.runAndWait(workflows.data[0].id, {
inputs: { query: "espresso" },
});
console.log(run.status);
// 2. Writ Cloud.
const cloud = new WritAgent({ apiKey: process.env.WRIT_API_KEY });
console.log((await cloud.cloud.scrape("https://example.com")).markdown);Python
from writ_agent import WritAgent
# 1. Writ Desktop
writ = WritAgent() # discovers the running engine + token
workflows = writ.workflows.list()
run = writ.workflows.run_and_wait(workflows.data[0]["id"], inputs={"query": "espresso"})
print(run.status)
# 2. Writ Cloud
cloud = WritAgent(api_key="wt_...")
print(cloud.cloud.scrape("https://example.com")["markdown"])AsyncWritAgent is the same API with await.
Go
// 1. Writ Desktop
client := writ.New()
workflows, err := client.Workflows.List(ctx, nil)
run, err := client.Workflows.RunAndWait(ctx, workflows.Data[0].ID, nil)
fmt.Println(run.Status)
// 2. Writ Cloud
cloud := writ.New(writ.WithAPIKey(os.Getenv("WRIT_API_KEY")))
page, err := cloud.Cloud.Scrape(ctx, "https://example.com")
fmt.Println(page.Markdown)Rust
// 1. Writ Desktop
let client = WritClient::discover().await?;
let workflows = client.workflows().list(None).await?;
let run = client.workflows().run_and_wait(workflows.data[0].id, None).await?;
println!("{}", run.status);
// 2. Writ Cloud
let cloud = CloudClient::from_env()?;
println!("{}", cloud.scrape("https://example.com").await?.markdown);Method names follow each language's conventions —
runAndWait/run_and_wait/RunAndWait. Consult the SDK's own README for exact signatures.
Because these implement one contract rather than four independent clients:
-
Discovery, identical everywhere: explicit config →
WRIT_API_URL/WRIT_TOKEN→$WRIT_HOME/runtime.json→~/.writ/active_profile→ that profile's descriptor →~/.writ/runtime.json→ a bounded profile scan. Each candidate is liveness-probed withGET /v1/agentbefore it is trusted. -
Uniform pagination. The daemon returns three different list envelopes (a bare array,
{data,count},{data,count,total}). All three normalize to onePage {data, count, total?}, so you never branch on which endpoint you called. -
Uniform errors, mapped from the daemon's several error shapes — including its plain-text framework rejections — plus the cloud's quota and billing conditions.
-
Live run events over SSE (
started/step/progress/finished/error), with a polling fallback if the stream drops. A stream that drops before a terminal event reconnects on its own and suppresses the frames you already received, so you see one continuous, gap-free, duplicate-free stream across a proxy timeout or a restart. -
monitors.watch()— detected changes as a continuous stream, in detection order, with no gaps and no repeats.Polling that feed by hand is harder than it looks: the newest-first view silently drops changes whenever more than
limitof them land between two polls, and a change row is updated (not re-inserted) when the same difference recurs, so an id you already processed can resurface.watch()drives the server's keyset cursor instead, so "everything after this point" is exact — and a resurfaced id arrives as what it actually is, a fresh detection. Persist the last change'slast_detected_at+idand hand them back assince/since_idto resume across restarts. -
Retries that cannot duplicate work. Transient failures (429, 408/425, 502/503/504, dropped sockets) retry with exponential backoff and full jitter, honouring
Retry-After— except when the server asks for longer than the SDK is willing to sleep, where you get the real response instead, which carries the reset time.GET/HEAD/OPTIONSalways retry.POST/PUT/PATCHretry only where the server honoursIdempotency-Key(Writ Cloud), and every attempt of one logical call reuses the same key, so the server replays its first answer instead of executing twice. Against Writ Desktop, which has no such lane, an unsafe method is never retried, because a secondPOSTthere is a second monitor. -
Webhook verification.
verify_webhook/verifyWebhook/VerifyWebhookauthenticates a delivery in constant time and enforces the replay window. VerifyX-Writ-Signature-V1, which covers"{timestamp}." + body; the body-onlyX-Writ-Signatureis still sent for handlers written before V1 and is refused by default, because nothing ties it to a point in time. There is a signing helper for the inbound direction too. -
Auto-pagination over
limit/offsetlist endpoints, so "list everything" is one loop instead of an offset walk you have to remember to write. -
run_and_waitthat times out without cancelling the run — the run continues server-side; the timeout bounds your wait, not its lifetime. -
max_agefreshness, one contract on both the workflow and the crawl side: "an answer collected within this many seconds is acceptable, otherwise go get it again". Every answer carries_cache.hit/_cache.age_secondsin the BODY — not only in headers, since an SDK caller receives a decoded payload and would never see a header. Omit it and nothing changes: work always runs. -
Saved crawls. A crawl row is one RUN whose id dies with it, so
crawl.save(...)stores the settings under a stable slug andcrawl.run_saved(...)re-runs exactly those — or hands back the pages it already collected whenmax_ageallows.crawl.saved_data(...)reads what is there at any age and never crawls. -
File assets on both sides of a run. A run can consume files (upload steps) and produce them (
wait_for_download), and each direction has one helper:file_slots(workflow)/fileSlots/FileSlotsreports what you may bind — the valid keys for the run'sfilesmap. Every upload step is an input. One that names a slot must be bound by you; one that just pins a file is keyedstep:<step id>and already runs, so binding it overrides that file for a single run instead of editing the workflow. Each entry carries the pinned file as its default, so you can tell the two apart without guessing.output_files(run)/outputFiles/OutputFilesreturns what the run captured —{file_id, filename, size, content_type, output_key?}— and the bytes come back through the ordinary files API. Both are derived from data you already hold, so neither costs a round trip and both work against any daemon version.wf = client.workflows.get(7) [s["slot"] for s in file_slots(wf)] # ['resume', 'step:6f2a…'] out = client.workflows.run_and_wait(7, files={"resume": "file_abc"}) for f in output_files(out): data = client.files.content(f["file_id"])
The binding specification is DESIGN.md; the wire is documented in
openapi/writ-agent.yaml (OpenAPI 3.1, 73 paths, 102
operations). It documents wire truth including the inconsistencies — that is
why the SDKs can paper over them. When a document and the daemon disagree, the
daemon wins.
typescript/ @usewrit/agent-sdk zero runtime dependencies
web/ @usewrit/web websites, via the Writ browser extension; zero runtime dependencies
server-node/ @usewrit/server the Writ Bridge's server side for Node; zero runtime dependencies
python/ writ-agent httpx
usewrit-python/ usewrit Writ Bridge, server side, for Python; cryptography + httpx
go/ .../writ-sdks/go standard library only
rust/ writ-client reqwest + serde
openapi/ writ-agent.yaml OpenAPI 3.1 description of the wire
codegen/ generate.sh Java/C#/Ruby/PHP via openapi-generator
DESIGN.md the binding cross-language contract
OAuth authorization-server endpoints (the SDKs consume tokens, they don't mint
them), the /mcp JSON-RPC surface — use
writ-mcp for that — OpenAI-compatible
routes, marketplace routes, backup/update/network/TLS administration, and the AI
surfaces. The record and AI-preview WebSockets are covered only as ticket minting.
Each SDK is independent — you can work on one without installing the others.
cd typescript && npm ci && npm test
cd python && pip install -e ".[dev]" && python -m pytest -q
cd go && go test -race ./...
cd rust && cargo test
cd web && npm ci && npm test
cd server-node && npm ci && npm test
cd usewrit-python && pip install -e ".[dev]" && python -m pytest -qEvery SDK also carries a live smoke test that discovers a running Writ Desktop
(writ-agentd) and makes read-only calls, skipped unless WRIT_SMOKE=1. See
CONTRIBUTING.md — note the two rules there: a behaviour
change belongs in all four SDKs in one pull request, and TypeScript and Go
stay at zero runtime dependencies.
| usewrit.app | Writ Cloud: build, run and schedule your website APIs. Start here. |
| usewrit/writ-desktop | Writ Desktop, the app these SDKs talk to on your computer. |
| usewrit/writ-mcp | Connect an MCP client to Writ Cloud with an API key. |
| usewrit/writ-plugins | The Writ plugin for Claude, Codex, Cursor, Gemini CLI and GitHub Copilot. |
| usewrit/writ-for-websites | Guides and examples for @usewrit/web, @usewrit/server and usewrit. |
MIT — see LICENSE.