Referencia API

Toda la superficie, endpoint por endpoint.

Writ responde en dos lugares: writ-agentd, el daemon agente en tu propia máquina en http://127.0.0.1:8131, y Writ Cloud en https://api.usewrit.app. Misma gramática JSON y mismo encabezado Bearer en ambos — familias de tokens distintas, y solo uno de los dos se factura.

superficies ▸ local + cloud

Dos superficies.

El daemon local es el software que la app de escritorio (o el agente autoalojado) mantiene en marcha: solo loopback, gratis. Writ Cloud es la superficie alojada que una clave wt_ desbloquea. Los SDKs descubren el primero y pueden llevar la segunda.

Un workflow publicado es una puerta aparte: POST /v1/{slug}/{path} en Writ Cloud, autenticado con una consumer key csk_ que acuñas para quienes lo llaman, documentada en los endpoints gestionados. El servidor MCP (JSON-RPC en /mcp) y las entregas webhook firmadas también tienen sus propias páginas: servidor MCP, webhooks.

auth ▸ cinco prefijos

Familias de tokens.

Un solo encabezado en todas partes: Authorization: Bearer …. Lo que cambia es la familia del token — cada prefijo está limitado a su superficie. Rotación y detalle de scopes: autenticación.

Acuñar una clave wlk_ exige el token runtime wlt_ — así una clave acotada filtrada nunca puede ampliarse a sí misma:

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

errores ▸ códigos estables

Una sola forma de error.

Los errores son objetos JSON pequeños: {"error": "…", "code": "…"} — una frase legible y un código estable. Los códigos:

runs ▸ el contrato

Semántica de ejecución.

El contrato que hay que entender antes de cablear nada:

• Asíncrono por defecto. POST /v1/workflows/{id}/run responde en cuanto la ejecución se despacha, con su id.
• O bloquea hasta el resultado. Añade ?wait=true — la llamada espera el veredicto. timeout está en segundos, acotado a 1–3600, 120 por defecto.
• Un run fallido es un resultado, no un error. Recibes la ejecución con status: "failed"; reserva el manejo de errores para transporte y auth.
• Dos formas de id. El feed de runs devuelve ids compuestos como workflow-3; cada llamada /v1/runs/{id}/* toma el id numérico de fila.

referencia ▸ 98 operaciones

La superficie local.

Cada operación del daemon local, exactamente como la enuncia la descripción OpenAPI — 98 operaciones en 16 grupos, todas bajo /v1 en loopback, todas autenticadas con Bearer.

Cada llamada tiene esta forma — un encabezado Bearer, JSON de entrada, JSON de salida:

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

Agente

Workflows

La semántica de arriba aplica a POST /v1/workflows/{id}/run. El par session gestiona la sesión del carril HTTP sin navegador que un workflow puede mantener.

Ejecuciones

GET /v1/runs/{id}/events transmite el progreso en vivo por SSE. Cancelar una ejecución ya resuelta responde 409 — con la propia ejecución como cuerpo.

Monitores

Selectores

Extractores

Atención al toggle: PATCH, no POST como en los selectores.

Automatizaciones

Personas

Secretos

Solo metadatos — ningún endpoint devuelve jamás el valor de un secreto.

Vault

Archivos

Datos

Conjuntos de datos

?format=json|csv|markdown|html — cualquier formato no-json responde texto renderizado en lugar de un cuerpo JSON.

Crawl

Las definiciones son crawls guardados e invocables. POST /v1/crawl/definitions/{ref}/run acepta max_age — un crawl previo lo bastante reciente se reutiliza en lugar de recargarse.

Claves

Acuñar exige el token runtime wlt_.

Tickets WebSocket

cloud ▸ medido + sin clave

La superficie cloud.

Writ Cloud es la superficie alojada y medida en https://api.usewrit.app. La spec declara ahí cuatro operaciones REST: el Scrape de una página con una clave wt_, más un nivel sin clave identificado solo por un id de dispositivo. Todo lo demás del host cloud — endpoints publicados, MCP, webhooks — se documenta en su propia página.

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"

referencia ▸ siguiente

Sigue construyendo.

faq

Preguntas de API, respondidas.

fin ▸ enviar

Apunta algo hacia ella.

El quickstart te lleva de la cuenta a la primera llamada en minutos; los SDKs envuelven toda esta página en clientes tipados.