API reference

The whole surface, endpoint by endpoint.

Writ answers in two places: writ-agentd, the agent daemon on your own machine at http://127.0.0.1:8131, and Writ Cloud at https://api.usewrit.app. Same JSON grammar and Bearer header on both — different token families, and only one of the two is metered.

surfaces ▸ local + cloud

Two surfaces.

The local daemon is the software the desktop app (or the self-hosted agent) keeps running: loopback-only and free. Writ Cloud is the hosted surface a wt_ key unlocks. The SDKs discover the first and can carry the second.

A published workflow is its own door: POST /v1/{slug}/{path} on Writ Cloud, authenticated with a csk_ consumer key you mint for its callers, documented on managed endpoints. The MCP server (JSON-RPC at /mcp) and signed webhook deliveries have their own pages too: MCP server, webhooks.

auth ▸ five prefixes

Token families.

One header everywhere: Authorization: Bearer …. What changes is the token family — each prefix is confined to its surface. Rotation and scope detail live in authentication.

Minting a wlk_ key requires the wlt_ runtime token — so a leaked scoped key can never widen itself:

const key = await client.keys.create({ name: "ci-runner", scopes: "read,run" });

key = client.keys.create("ci-runner", scopes="read,run")

key, err := client.Keys.Create(ctx, "ci-runner", "read,run")

let key = agent.keys().create("ci-runner", Some("read,run")).await?;

# Minting keys requires the full-access runtime token (wlt_)
curl -X POST http://127.0.0.1:8131/v1/keys \
  -H "Authorization: Bearer $WRIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-runner", "scopes": "read,run"}'

errors ▸ stable codes

One error shape.

Errors are small JSON objects: {"error": "…", "code": "…"} — a human sentence and a stable code. The codes:

runs ▸ the contract

Run semantics.

The one contract to understand before wiring anything:

• Async by default. POST /v1/workflows/{id}/run answers as soon as the run is dispatched, with the run id.
• Or block for the result. Add ?wait=true — the call holds until the run settles. timeout is in seconds, clamped to 1–3600, default 120.
• A failed run is a result, not an error. You get the run back with status: "failed"; keep error handling for transport and auth problems.
• Two id shapes. The run feed returns composite ids like workflow-3; every /v1/runs/{id}/* call takes the numeric row id.

reference ▸ 98 operations

The local surface.

Every operation of the local daemon, exactly as the OpenAPI description states it — 98 operations in 16 groups, all under /v1 on loopback, all Bearer-authenticated.

Every call is this shape — one Bearer header, JSON in, JSON out:

# Local agent daemon — loopback, wlt_/wlk_ token (use 127.0.0.1, not localhost)
curl -X POST http://127.0.0.1:8131/v1/monitors \
  -H "Authorization: Bearer $WRIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing"}'

Agent

Workflows

The run semantics above apply to POST /v1/workflows/{id}/run. The session pair manages the browserless HTTP-lane session a workflow can hold.

Runs

GET /v1/runs/{id}/events streams live progress over SSE. Cancelling a run that has already settled answers 409 — with the run itself as the body.

Monitors

Selectors

Extractors

Note the toggle: PATCH, not POST as on selectors.

Automations

Personas

Secrets

Metadata only — no endpoint ever returns a secret value.

Vault

Files

Data

Datasets

?format=json|csv|markdown|html — any non-json format answers rendered text instead of a JSON body.

Crawl

Definitions are saved, callable crawls. POST /v1/crawl/definitions/{ref}/run accepts max_age — a recent-enough previous crawl is reused instead of fetched again.

Keys

Minting requires the wlt_ runtime token.

WebSocket tickets

cloud ▸ metered + keyless

The cloud surface.

Writ Cloud is the hosted, metered surface at https://api.usewrit.app. The spec declares four REST operations there: one-page Scrape with a wt_ key, plus a keyless tier identified only by a device id. Everything else on the cloud host — published endpoints, MCP, webhooks — is documented on its own page.

const cloud = new CloudApi({ apiKey: process.env.WRIT_API_KEY }); // wt_…
const page = await cloud.scrape("https://example.com");
const site = await cloud.map("https://example.com", { search: "pricing", limit: 20 });
console.log(cloud.tier); // "metered" | "keyless"

cloud = Cloud(api_key=os.environ["WRIT_API_KEY"])  # wt_… — no daemon needed
page = cloud.scrape("https://example.com")
site = cloud.map("https://example.com", search="pricing", limit=20)
print(cloud.tier)  # "metered" | "keyless"

# Metered — wt_ API key, billed from your credit pool
curl -X POST https://api.usewrit.app/api/crawl/scrape \
  -H "Authorization: Bearer $WRIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Keyless — no account, no key: a stable device id is the only identity.
# 429 keyless_rate_limited when the allowance is spent.
curl -X POST https://api.usewrit.app/v1/keyless/scrape \
  -H "X-Writ-Client-Id: $WRIT_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
curl https://api.usewrit.app/v1/keyless/quota -H "X-Writ-Client-Id: $WRIT_CLIENT_ID"

reference ▸ next

Keep building.

faq

API questions, answered.

end ▸ ship

Point something at it.

The quickstart takes you from account to first call in minutes; the SDKs wrap this whole page in typed clients.