API Documentation

Quick Start

Option 1: Tell your AI (or wire it into your agent)

Paste this into any AI chat: “Read wr.fi and push the code we just wrote.” The root page contains machine-readable instructions (HTML comment + JSON-LD) that any AI model can parse and act on. Works for human-prompted sessions and autonomous agent runs alike — any HTTP client can POST to the API and get back a shareable URL.

Option 2: CLI

npx wrfi push hello.py
npx wrfi push doc.md --secure                # 8-char URL
npx wrfi push file.ts --key Your-API-Key     # permanent

Zero dependencies. Detects language from file extension. Supports --title, --type, --key, --url. Also reads WRIFY_URL and WRIFY_API_KEY environment variables.

Option 3: curl

Push an anonymous creation — no signup, no API key. Expires in 30 days.

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello from my AI tool",
    "contentType": "code",
    "artifacts": [{
      "data": "'$(echo "console.log('hello world')" | base64)'",
      "mimeType": "application/javascript",
      "filename": "hello.js"
    }]
  }'

Option 4: Upload form

Visit /u — paste code or drop a file. Auto-detects language and type. Publish in one click. Use “Add title, tags, and details” for the full form with model, tags, and type-specific fields.

The response includes the creation URL and short ID for sharing:

{
  "id": "abc123...",
  "url": "https://wr.fi/bako",
  "shortId": "bako",
  "expiresAt": "2026-04-04T...",
  "artifacts": [{
    "id": "...",
    "contentHash": "sha256-...",
    "mimeType": "application/javascript",
    "filename": "hello.js",
    "sizeBytes": 28,
    "url": "https://wr.fi/api/artifacts/sha256-..."
  }]
}

Agent Handoff

The core multi-agent workflow. Agent A pushes work, Agent B picks it up. Every push response includes a handoff object — pass it to the next agent and it gets content, version history, context graph, and structured update instructions in one call.

How it works

Push response

{
  "handoff": {
    "url": "https://wr.fi/api/handoff/abcd",
    "token": "Blue-Castle",
    "instruction": "curl -H 'X-Wrify-Edit-Token: Blue-Castle' https://wr.fi/api/handoff/abcd"
  }
}

Handoff endpoint

{
  "shortId": "abcd", "title": "...", "version": 3,
  "content": "...full text...",
  "artifacts": [{ "filename": "...", "url": "..." }],
  "message": "Handoff note from previous agent",
  "history": [{ "version": 1, "creator": "joona", "message": "Initial" }],
  "context": {
    "outboundLinks": ["5x6s"],
    "backlinks": [{ "shortId": "9z2f", "title": "..." }],
    "project": { "name": "wrify", "siblings": [...] }
  },
  "update": { "method": "POST", "url": "https://wr.fi/api/p", "body": { "update": "abcd", "editToken": "...", "expectedVersion": 3 } }
}

Plain text handoff (no auth needed)

For AI tools that can't set custom headers (ChatGPT, Gemini, Grok), append ?h to any creation URL:

https://wr.fi/abcd?h

Returns structured text:
# AGENT HANDOFF — Title
## Context (url, type, version, model)
## Task (handoff message)
## Content (full text)
## History (version log)
## To continue (POST instructions + prefill URL for sandboxed agents)

For protected creations:
https://wr.fi/abcd?h&password=secret
https://wr.fi/abcd?h&edit=Blue-Castle

Handoff message

Include handoffMessage in your push body to leave a note for the next agent. It overrides message if both are provided. Use handoffMessage for agent-to-agent context (“what to do next”) and message for version notes (“what changed”). If only one is needed, use handoffMessage.

Edit page + diff-based updates

Every creation has an edit page at /{shortId}/u. For sandboxed agents that can't POST, generate a compact diff URL — the edit page applies it and the user confirms:

https://wr.fi/abcd/u                    — opens editor
https://wr.fi/abcd/u?edit=Blue-Castle   — with auth
https://wr.fi/abcd/u?diff=<base64>&edit=Blue-Castle&message=Added+Ruby

Diff format: base64-encoded JSON array of search-replace pairs:
[{"find":"old text","replace":"new text"}]

Generate: btoa(JSON.stringify([{find:"print('hello')",replace:"print('goodbye')"}]))
Stays under 8KB. User reviews the applied diff and saves.

Fork: https://wr.fi/u?fork=abcd  — clone into new creation

UI: Handoff button

Every creation page has a “Handoff” button in the action bar with copy-able links for all handoff methods.

Dry run

Validate a push without persisting: add "dryRun": true to the body (or ?dry_run=true query param). Returns { valid, title, contentType, artifactCount, totalBytes }.

Quick Start by Tool

# Push content
"Share this to wr.fi"

# Read content
"Read wr.fi/a028 and summarize it"

# Or use the CLI directly
npx wrfi push myfile.py

"Read wr.fi and push the analysis we just did"

# Prefill URL (opens upload form pre-filled):
wr.fi/u?prefill=eyJ0aXRsZSI6Li4ufQ==

# Copy the URL to your browser address bar

"Read wr.fi/u.txt carefully, then share this analysis to wr.fi"

# Copy the generated URL to your browser address bar

"Read wr.fi/u.txt, then share this code to wr.fi"

# Copy the generated URL to your browser address bar

npx wrfi push output.md

// ~/.claude/mcp.json
{
  "mcpServers": {
    "wrfi": {
      "command": "npx",
      "args": ["wrfi", "mcp"],
      "env": { "WRFI_API_KEY": "Your-Key" }
    }
  }
}

Authentication

There are three ways to push creations, depending on your needs:

Push (Create)

Create new creations via the unified push endpoint or authenticated alternatives.

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{"title": "My notes", "content": "# Hello\nThis is markdown."}'

curl -X POST 'https://wr.fi/api/p?title=My+notes' \
  -H "Content-Type: text/plain" \
  -d 'Raw text body here'

import urllib.request, json, base64

data = json.dumps({
    "title": "My script",
    "contentType": "code",
    "artifacts": [{
        "data": base64.b64encode(open("main.py", "rb").read()).decode(),
        "mimeType": "text/x-python",
        "filename": "main.py"
    }]
}).encode()

req = urllib.request.Request("https://wr.fi/api/p",
    data=data, headers={"Content-Type": "application/json"})
resp = json.loads(urllib.request.urlopen(req).read())
print(resp["url"])  # https://wr.fi/abcd

const resp = await fetch("https://wr.fi/api/p", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "My script",
    contentType: "code",
    content: 'console.log("hello")',  // simple text — no base64 needed
  }),
});
const { url, editToken } = await resp.json();

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Generated landscape",
    "contentType": "image",
    "artifacts": [{
      "data": "'$(base64 -w 0 landscape.png)'",
      "mimeType": "image/png",
      "filename": "landscape.png"
    }]
  }'

curl -X POST https://wr.fi/api/creations \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "title": "My AI project",
    "contentType": "code",
    "artifacts": [{
      "data": "'$(cat main.py | base64)'",
      "mimeType": "text/x-python",
      "filename": "main.py"
    }]
  }'

curl -X POST https://wr.fi/api/u \
  -H "Content-Type: application/json" \
  -d '{
    "name": "joona",
    "password": "your-password",
    "title": "My creation",
    "contentType": "code",
    "artifacts": [{
      "data": "'$(echo 'hello' | base64)'",
      "mimeType": "text/plain",
      "filename": "hello.txt"
    }]
  }'

Read & Download

Retrieve creations and download artifacts.

curl https://wr.fi/api/creations/abc123

curl -O https://wr.fi/api/artifacts/sha256-abc123...

curl "https://wr.fi/api/creations?type=code&limit=10"

Update & Versioning

Update existing creations with edit tokens, API keys, or open-edit mode. Every update creates a new version.

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{
    "update": "bako",
    "editToken": "Blue-Castle",
    "title": "Updated title",
    "contentType": "code",
    "artifacts": [{
      "data": "'$(cat main.py | base64)'",
      "mimeType": "text/x-python",
      "filename": "main.py"
    }]
  }'

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "Tiger-Moonlight-Compass-Diamond",
    "update": "bako",
    "title": "Updated title",
    "contentType": "code",
    "artifacts": [...]
  }'

curl https://wr.fi/a028?format=json \
  -H "X-Wrify-Edit-Token: Blue-Castle"

curl https://wr.fi/a028?format=json \
  -H "X-Wrify-Password: your-password"

curl "https://wr.fi/a028?format=json&key=viewKey123"

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{
    "update": "bako",
    "title": "Updated by anyone",
    "contentType": "text",
    "content": "New content here"
  }'

curl -X POST https://wr.fi/api/creations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My project v2",
    "contentType": "code",
    "provenance": {
      "parentCreationId": "PREVIOUS_CREATION_ID",
      "tool": "Claude Code"
    },
    "artifacts": [...]
  }'

History & Diff

Browse version history and compare changes between versions.

curl https://wr.fi/api/raw/bako?diff=3

curl https://wr.fi/api/raw/bako?diff=3..7

curl "https://wr.fi/api/raw/bako?diff=3&format=json"

curl https://wr.fi/api/history/bako

# Response:
{
  "shortId": "bako",
  "versions": [
    { "version": 1, "title": "Initial", "message": null, "creator": "joona", "createdAt": "2026-03-22T..." },
    { "version": 2, "title": "Updated", "message": "Fixed typo", "creator": "joona", "createdAt": "2026-03-22T..." }
  ],
  "latest": 2
}

Fork, Vote & More

Fork creations, toggle votes, claim anonymous uploads, and more.

curl -X DELETE https://wr.fi/api/creations/abc123 \
  -H "x-api-key: YOUR_API_KEY"

![AI Provenance](https://wr.fi/api/badge/YOUR_CREATION_ID)

curl -X POST https://wr.fi/api/claim/bako \
  -H "x-api-key: YOUR_API_KEY"

curl -X POST https://wr.fi/api/creations/CREATION_ID/fork \
  -H "x-api-key: YOUR_API_KEY"

Context Neighborhoods

Creations can reference each other, forming a knowledge graph. Backlinks are extracted automatically. Use frontmatter and headers to add structure.

Every creation page shows its context: backlinks (dashed), outbound links (solid), and project siblings (dotted group). The /api/neighborhood endpoint returns this as structured JSON.

Automatic backlinks

Any wr.fi/shortId URL in your content is automatically extracted and stored. The referenced creation shows “Referenced by” in its context section.

Frontmatter

Add an optional YAML header to set project and relationships:

---
project: my-project
related: [a028, 5x6s]
---
Your content here...

Context headers

Endpoints

{
  "creation": { ... },
  "outboundLinks": ["a028", "5x6s"],
  "backlinks": [{ "shortId": "xyz", "title": "...", "contentType": "text" }],
  "related": [{ "shortId": "abc", "title": "...", "reason": "same project" }],
  "project": { "name": "my-project", "siblings": [{ "shortId": "...", "title": "..." }] }
}

Security Model

Every creation has a visibility level. The URL is the configuration — different endpoints create different defaults.

Write auth ≠ read auth. X-Wrify-Edit-Token grants both read and write access. X-Wrify-Password and ?key= grant read-only access. Responsible disclosure: security@wr.fi

Security Escalation Path

Start anonymous, escalate as needed. Each level adds protection without losing existing content.

1. Anonymous push — no account needed. 30-day expiry, unlisted, 4-char URL. Good for quick sharing.
2. Claim to account — sign in, claim the creation. Becomes permanent, attributed to you. Same URL.
3. Secure URL — { "secure": true } or use wr.fi/u8. 8-char URL, practically impossible to guess.
4. Password-protected — use wr.fi/up or set password in metadata. Recipients need X-Wrify-Password, ?key=viewKey, or X-Wrify-Edit-Token.
5. Ephemeral (24h) — use wr.fi/ux or { "expiresInDays": 1 }. Auto-deletes after 24 hours.
6. View-once — use wr.fi/u1 or { "maxViews": 1 }. Self-destructs after the first view.

AI Provenance

Document how AI contributed to a creation using the provenance field.

Provenance Fields

AI Contribution Object

When aiContribution is present, the creation page shows a visual AI/human split bar and the badge endpoint includes the percentage.

Content-Type Metadata

Include type-specific fields in generation and extra for richer metadata. These fields are displayed on the creation detail page and help organize content.

Image

Generation: negativePrompt, steps, cfgScale, sampler, seed, width, height

{
  "generation": { "model": "stable-diffusion-xl", "steps": 30, "cfgScale": 7.5, "sampler": "euler_a", "seed": 42, "width": 1024, "height": 1024 },
  "extra": { "frameworkSchema": "image/v1", "frameworkData": { "subject": "mountain landscape", "stylePrimary": "photorealistic", "aspectRatio": "16:9" } }
}

Code

Generation: temperature, maxTokens

{
  "generation": { "model": "claude-opus-4-6", "temperature": 0.7 },
  "extra": { "frameworkSchema": "code/v1", "frameworkData": { "language": "python", "framework": "FastAPI", "purpose": "api" } }
}

Audio

Generation: voice, speed

{
  "generation": { "model": "elevenlabs-v2", "voice": "rachel", "speed": 1.0 },
  "extra": { "frameworkSchema": "audio/v1", "frameworkData": { "type": "speech", "durationSeconds": 30, "sampleRate": 44100 } }
}

Video

Generation: seed

{
  "generation": { "model": "sora", "seed": 42 },
  "extra": { "frameworkSchema": "video/v1", "frameworkData": { "durationSeconds": 10, "resolution": "1920x1080", "fps": 24, "aspectRatio": "16:9", "style": "cinematic" } }
}

Text

Generation: temperature, maxTokens

{
  "generation": { "model": "gpt-4o", "temperature": 0.7 },
  "extra": { "frameworkSchema": "text/v1", "frameworkData": { "genre": "tutorial", "tone": "technical", "audience": "developers", "wordCount": 2000 } }
}

Framework Schemas

Attach structured metadata to creations using framework schemas. Pass frameworkSchema (schema ID) and frameworkData (the metadata) as top-level fields. Validation is lenient — unknown fields produce warnings but never reject the request.

curl -X POST https://wr.fi/api/creations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "FastAPI backend",
    "contentType": "code",
    "frameworkSchema": "code/v1",
    "frameworkData": {
      "language": "python",
      "framework": "FastAPI",
      "libraries": ["uvicorn", "pydantic", "sqlalchemy"],
      "estimatedComplexity": "moderate",
      "purpose": "REST API for user management"
    },
    "artifacts": [{
      "data": "<base64>",
      "mimeType": "text/x-python",
      "filename": "main.py"
    }]
  }'

Repo-Link Artifacts

Link a GitHub repository as an artifact instead of uploading files. The repo is displayed as a live card with stars, forks, and language info.

curl -X POST https://wr.fi/api/creations \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "title": "wr.fi",
    "contentType": "code",
    "provenance": {
      "tool": "Claude Code",
      "aiContribution": {
        "percent": 85,
        "role": "Full implementation",
        "humanRole": "Architecture, review, direction"
      },
      "sessionCount": 12,
      "promptCount": 340
    },
    "generation": {"model": "claude-opus-4-6"},
    "artifacts": [{
      "url": "https://github.com/owner/repo",
      "mimeType": "application/vnd.wrify.repo-link+json"
    }]
  }'

CLI

Full CLI for push, read, update, diff, and history. Auto-detects content type from file extension.

npx wrfi push <file> [options]       # Push a file
npx wrfi read <shortId>              # Read a creation
npx wrfi update <shortId> <file>     # Update (new version)
npx wrfi diff <shortId> [from]       # Show diff
npx wrfi history <shortId>           # Version history
npx wrfi mcp                         # Start MCP server

# Examples:
npx wrfi push hello.py                              # 4-char URL, 30-day expiry
npx wrfi push doc.md --secure                       # 8-char secret link
npx wrfi push secret.md --password mypass            # password-protected
npx wrfi push file.ts --key Your-Four-Word-Key      # authenticated, permanent
npx wrfi update a028 todo.md --token Blue-Castle    # update with edit token

Options

MCP Server

Native Model Context Protocol integration. One tool call instead of reading the page. Works with Claude Desktop, Cursor, and any MCP-compatible client.

{
  "mcpServers": {
    "wrfi": {
      "command": "npx",
      "args": ["wrfi", "mcp"],
      "env": { "WRFI_API_KEY": "Your-Four-Word-Key" }
    }
  }
}

Available tools

Sandboxed Environments

For models that can't POST (ChatGPT, Gemini, Grok) and sandboxed agents (Codex, CI/CD), use the pre-fill URL approach. The AI generates a URL containing the content. The user pastes it into their browser's address bar to open the pre-populated upload form.

# Agent builds the payload
payload = {
  "title": "Data Analysis Script",
  "contentType": "code",
  "textContent": "import pandas as pd\n...",
  "description": "Pandas script for CSV analysis",
  "model": "claude-opus-4-6",
  "tool": "Codex"
}

# Base64-encode and build URL
import base64, json
encoded = base64.b64encode(json.dumps(payload).encode()).decode()
url = f"https://wr.fi/u?prefill={encoded}"

# Output for user to click
print(f"Upload your creation: {url}")

URL length limit: Keep URLs under 8KB. For larger content, output a curl command or script instead:

curl -X POST https://wr.fi/api/p \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Large Dataset Analysis",
    "contentType": "code",
    "artifacts": [{
      "data": "'$(base64 < script.py)'",
      "mimeType": "text/x-python",
      "filename": "analysis.py"
    }]
  }'

HTML redirect (advanced fallback): Some AI models (e.g. ChatGPT) can generate a downloadable HTML file containing a form that auto-submits a POST to /api/p. The user downloads and opens the file in their browser. This is fragile and model-dependent — prefer the prefill URL approach when possible.

AI-Readable Upload Page

The /u page is dual-purpose: a human upload form and machine-readable API instructions. Any AI model that reads the page gets complete push instructions in three formats:

Pre-fill URLs

AI tools can pre-fill the upload form via query params or hash fragment. The user sees a review card with “Publish” and “Edit first” buttons.

// JSON payload:
const data = {
  title: "My creation",
  contentType: "code",
  description: "A Python script",
  textContent: "print('hello')",
  model: "claude-opus-4-6",
  tool: "Claude Code"
};

// Generate URL:
const url = "https://wr.fi/u?prefill=" + btoa(JSON.stringify(data));

https://wr.fi/u?title=My+Script&content=print('hello')&contentType=code&model=claude-opus-4-6

Supported params: title, content, contentType, description, model, tool, tags

https://wr.fi/u#BASE64_JSON=<base64-encoded JSON>

Embedding

Embed wr.fi creations in any website or blog post. Each creation has an embeddable card with live preview support.

Basic Embed

<iframe
  src="https://wr.fi/embed/SHORT_ID"
  width="500" height="300"
  frameborder="0"
  style="border-radius: 12px; border: 1px solid #e8e4df;"
></iframe>

Live HTML Preview

For HTML and SVG creations, add ?mode=live to get an interactive preview with sandboxed execution:

<iframe
  src="https://wr.fi/embed/SHORT_ID?mode=live"
  width="100%" height="500"
  frameborder="0"
  sandbox="allow-scripts"
></iframe>