Référence API

Toute la surface, endpoint par endpoint.

Writ répond à deux endroits : writ-agentd, le daemon agent sur votre propre machine à http://127.0.0.1:8131, et Writ Cloud à https://api.usewrit.app. Même grammaire JSON et même en-tête Bearer des deux côtés — familles de tokens différentes, et un seul des deux est facturé.

surfaces ▸ local + cloud

Deux surfaces.

Le daemon local est le logiciel que l’app de bureau (ou l’agent auto-hébergé) fait tourner : loopback uniquement, gratuit. Writ Cloud est la surface hébergée qu’une clé wt_ déverrouille. Les SDKs découvrent le premier et peuvent porter la seconde.

Un workflow publié est une porte à part : POST /v1/{slug}/{path} sur Writ Cloud, authentifié par une consumer key csk_ que vous fabriquez pour ses appelants, documentée sur les endpoints gérés. Le serveur MCP (JSON-RPC sur /mcp) et les livraisons webhook signées ont aussi leurs propres pages : serveur MCP, webhooks.

auth ▸ cinq préfixes

Familles de tokens.

Un seul en-tête partout : Authorization: Bearer …. Ce qui change, c’est la famille du token — chaque préfixe est cantonné à sa surface. Rotation et détail des scopes : authentification.

Fabriquer une clé wlk_ exige le token runtime wlt_ — une clé restreinte qui fuite ne peut donc jamais s’élargir elle-même :

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"}'

erreurs ▸ codes stables

Une seule forme d’erreur.

Les erreurs sont de petits objets JSON : {"error": "…", "code": "…"} — une phrase lisible et un code stable. Les codes :

runs ▸ le contrat

Sémantique des exécutions.

Le contrat à comprendre avant de câbler quoi que ce soit :

• Asynchrone par défaut. POST /v1/workflows/{id}/run répond dès que l’exécution est dispatchée, avec son id.
• Ou bloquez jusqu’au résultat. Ajoutez ?wait=true — l’appel attend le verdict. timeout est en secondes, borné à 1–3600, 120 par défaut.
• Un run en échec est un résultat, pas une erreur. Vous récupérez l’exécution avec status: "failed" ; réservez la gestion d’erreurs au transport et à l’auth.
• Deux formes d’id. Le fil des runs renvoie des ids composites comme workflow-3 ; chaque appel /v1/runs/{id}/* prend l’id numérique de ligne.

référence ▸ 98 opérations

La surface locale.

Chaque opération du daemon local, exactement comme la description OpenAPI l’énonce — 98 opérations en 16 groupes, toutes sous /v1 en loopback, toutes authentifiées par Bearer.

Chaque appel a cette forme — un en-tête Bearer, JSON en entrée, JSON en sortie :

# 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

La sémantique ci-dessus s’applique à POST /v1/workflows/{id}/run. La paire session gère la session de la voie HTTP sans navigateur qu’un workflow peut détenir.

Exécutions

GET /v1/runs/{id}/events diffuse la progression en direct via SSE. Annuler une exécution déjà réglée répond 409 — avec l’exécution elle-même en corps.

Moniteurs

Sélecteurs

Extracteurs

Notez le toggle : PATCH, et non POST comme côté sélecteurs.

Automatisations

Personas

Secrets

Métadonnées uniquement — aucun endpoint ne renvoie jamais la valeur d’un secret.

Vault

Fichiers

Données

Jeux de données

?format=json|csv|markdown|html — tout format non-json répond du texte rendu plutôt qu’un corps JSON.

Crawl

Les définitions sont des crawls enregistrés et rappelables. POST /v1/crawl/definitions/{ref}/run accepte max_age — un crawl précédent assez récent est réutilisé au lieu d’être rechargé.

Clés

La fabrication exige le token runtime wlt_.

Tickets WebSocket

cloud ▸ facturé + sans clé

La surface cloud.

Writ Cloud est la surface hébergée et facturée à https://api.usewrit.app. La spec y déclare quatre opérations REST : le Scrape d’une page avec une clé wt_, plus un palier sans clé identifié par un simple id d’appareil. Tout le reste de l’hôte cloud — endpoints publiés, MCP, webhooks — est documenté sur sa propre 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"

référence ▸ suite

Continuer à construire.

faq

Questions API, répondues.

fin ▸ livrer

Branchez quelque chose dessus.

Le quickstart vous mène du compte au premier appel en quelques minutes ; les SDKs enveloppent toute cette page dans des clients typés.