# VaultForge — Privacy-First Secure Document Processing Web App | AI Agent Guide
# https://vaultforge.work
# Machine-readable documentation for LLM agents and automated tools.
# Last updated: 2026-04-11

## What is VaultForge?

VaultForge is a privacy-first secure document processing web app — usable entirely in the browser with no account required for basic tasks.
It merges PDFs, runs OCR, redacts PII, converts images, compresses files, removes backgrounds, upscales images, and more — all processed in isolated server memory with zero data retention.
Files are never written to disk, never stored in the cloud, and never logged. Privacy is architecturally guaranteed, not a policy.

Web app: https://vaultforge.work (free to use, no login required for basic tools)
REST API: also available for developers and AI agents (Pro/Business API key or L402 Lightning pay-per-request — no account required for L402).

All processing is ephemeral — zero cloud storage. Files expire in 30 minutes after processing.

---

## Machine-Readable Resources

- OpenAPI 3.0 spec:  https://vaultforge.work/api/v1/openapi.json
- Plain-text guide:   https://vaultforge.work/api/agent-guide
- AI plugin manifest: https://vaultforge.work/.well-known/ai-plugin.json

---

## Base URL

  https://vaultforge.work/api/v1

---

## Authentication — Required on All Processing Endpoints

There is NO free tier for API access. Every API request must use one of the two methods below.
Free accounts can use all tools through the web UI at https://vaultforge.work (no API key needed there).

### Method 1: API Key (Pro or Business plan required)

  Header: X-API-Key: <your_api_key>

  Requires an active Pro ($3.99/mo) or Business ($9.99/mo) subscription.
  Free accounts receive HTTP 403 with an upgrade URL.
  Get an API key at https://vaultforge.work/api-docs after upgrading.

### Method 2: L402 Lightning (no account required, pay-per-request)

  The simplest path for agents and automation — no signup, no subscription.

  Step 1 — Make your API request WITHOUT any auth header.
           The server responds 402 Payment Required with a BOLT11 Lightning invoice.

  Step 2 — Pay the BOLT11 invoice with any Lightning wallet
           (Alby, Phoenix, Breez, Mutiny, Zeus, etc.).
           After payment, your wallet shows a 64-char hex "payment preimage".

  Step 3 — Retry the SAME request with this header:
           Authorization: L402 <payment_hash>:<payment_preimage>

           Where:
             payment_hash     = the "id" field from the 402 response invoice object (64-char hex)
             payment_preimage = the 64-char hex preimage from your wallet after paying

  Verification: The server checks sha256(preimage) == payment_hash cryptographically.
                No account needed. The token is valid for 24 hours after first use.

---

## All Endpoints

### GET /api/v1/openapi.json
  Returns the full OpenAPI 3.0 specification.
  No auth required.

### GET /api/v1/me
  Returns your account tier, token balance, daily usage, and API key info.
  Requires: X-API-Key header (Pro or Business plan).

### POST /api/v1/convert   [Pro+ API key or L402]
  Convert images between formats.
  Input:  multipart/form-data
  Fields:
    file       — the image file (JPEG, PNG, WebP, AVIF, GIF, BMP, TIFF, HEIC, HEIF)
    to         — target format: jpeg | png | webp | avif | gif | bmp | tiff
    quality    — (optional) 1-100, default 85
    use_tokens — (optional) "true" to spend tokens if daily limit is reached
  Output: binary file stream (the converted image)
  L402 cost: ~$0.05 (~50 sats at current BTC price)

### POST /api/v1/compress-image   [Pro+ API key or L402]
  Compress an image to reduce file size.
  Input:  multipart/form-data
  Fields:
    file          — JPEG, PNG, WebP, TIFF, or HEIC image
    quality       — (optional) 10-100, default 80
    output_format — (optional) jpeg | png | webp | avif, default: jpeg
    keep_metadata — (optional) "true" to preserve EXIF
  Output: JSON with downloadUrl, savedPercent, filename

### POST /api/v1/compress-pdf   [Pro+ API key or L402]
  Compress a PDF document.
  Input:  multipart/form-data
  Fields:
    file — PDF file
  Output: JSON with downloadUrl, savedPercent, filename

### POST /api/v1/merge   [Pro+ API key or L402]
  Merge 2-50 PDF files into one.
  Input:  multipart/form-data
  Fields:
    files    — 2 to 50 PDF files (field name MUST be exactly "files", NOT "files[]")
    password — (optional) password-protect the merged PDF
  Output: JSON with downloadUrl, filename

### POST /api/v1/ocr   [Pro+ API key or L402]
  Extract text from an image or PDF using OCR.
  Input:  multipart/form-data
  Fields:
    file — image or PDF
    lang — (optional) language code, default: eng (English)
  Output: JSON with text (extracted text), pages, confidence

### POST /api/v1/pii-redact   [Pro+ API key or L402]
  Detect and redact PII (names, emails, phone numbers, SSNs, credit cards) from documents.
  WARNING: Only PDF and TXT files are accepted. Images (.jpg/.png) will return HTTP 400.
  Input:  multipart/form-data
  Fields:
    file — PDF or TXT file ONLY (not images)
  Output:
    PDF input → JSON { fileId, filename, downloadUrl, totalRedacted, counts, tokensUsed }
    TXT input → JSON { redactedText, totalRedacted, counts, tokensUsed }

### POST /api/v1/bg-remove   [Business API key or L402]
  Remove background from an image (returns transparent PNG).
  Input:  multipart/form-data
  Fields:
    file — JPEG, PNG, or WebP image
  Output: JSON with downloadUrl (transparent PNG)

### POST /api/v1/upscale   [Business API key or L402]
  AI upscale an image 2x or 4x.
  Input:  multipart/form-data
  Fields:
    file  — JPEG, PNG, or WebP image
    scale — 2 or 4 (default: 2)
  Output: JSON with downloadUrl, originalSize, newSize

### POST /api/v1/images-to-pdf   [Pro+ API key or L402]
  Combine multiple images into a single PDF.
  Input:  multipart/form-data
  Fields:
    files — image files (JPEG, PNG, WebP, GIF, BMP, AVIF), field name MUST be exactly "files", NOT "files[]"
  Output: JSON with downloadUrl, filename

### POST /api/v1/exif-remove   [Pro+ API key or L402]
  Strip all EXIF metadata from an image.
  Input:  multipart/form-data
  Fields:
    file — image file
  Output: JSON with downloadUrl, filename

### POST /api/v1/doc-to-markdown   [Pro+ API key or L402]
  Convert a document to clean, structured Markdown optimized for LLMs and RAG pipelines.
  Accepted formats: PDF, DOCX, PPTX, XLSX, HTML (NOT images).
  Input:  multipart/form-data
  Fields:
    file — the document file
  Output: JSON { markdown, wordCount, charCount, tokensUsed }
  L402 cost (tiered by file size):
    < 1 MB   → ~$0.20 / 4 tokens
    1–10 MB  → ~$0.40 / 8 tokens
    10–50 MB → ~$0.80 / 16 tokens
    > 50 MB  → ~$1.20 / 24 tokens

### POST /api/v1/tokens/lightning-topup   [L402 — no account needed]
  Pre-fund a session credential using a Lightning payment. Autonomous-agent friendly.
  Input:  JSON body
  Fields:
    tokens — how many to purchase (1–1000, default: 10). Price: $0.03 per token.
  Flow:
    1. POST without auth → receive 402 with BOLT11 invoice
    2. Pay invoice → get 64-char hex preimage from wallet
    3. Retry with: Authorization: L402 <payment_hash>:<preimage>
    4. Response: { success: true, tokens_granted: N, message: "..." }
  HOW TO USE THE SESSION CREDENTIAL:
    The "Authorization: L402 <payment_hash>:<preimage>" header from step 3 is your session key.
    Send it unchanged on every API endpoint call you make for the next 24 hours.
    No new 402 invoice is triggered — the server sees the credential as already paid.
    The same header works on ALL endpoints (compress, OCR, merge, doc-to-markdown, etc.)
    until it expires (24 h from first use).
  Note: The token count controls the invoice price only. A 10-token topup costs $0.30 and
        gives the same 24-hour session credential as a 1-token ($0.03) purchase.

### POST /api/v1/tokens/buy   [API key or L402]
  Returns a Stripe checkout URL to purchase a permanent token pack.
  IMPORTANT: This does NOT complete a purchase — it returns a URL the user must visit in a browser.
  Use /tokens/lightning-topup instead for autonomous agent purchases.
  Input:  JSON body
  Fields:
    pack — REQUIRED: "basic" | "standard" | "pro"
  Token packs:
    basic    →  100 tokens  $2.99
    standard →  500 tokens  $9.99
    pro      → 2000 tokens  $29.99
  Output: JSON { checkoutUrl, tokens, price_usd, note }

### GET /api/v1/history   [API key required — Pro or Business]
  Returns your last 50 API conversion records (L402 sessions return empty — no persistent history).
  Output: JSON { total, offset, limit, items: [...] }

---

## Response Format (file processing endpoints)

  Success (200):
    {
      "fileId":       "abc123",
      "filename":     "output.webp",
      "downloadUrl":  "https://vaultforge.work/api/store/abc123/output.webp",
      "tokensUsed":   1,
      "originalSize": 204800
    }

  For /api/v1/convert, the converted file is streamed directly (binary response, not JSON).
  Content-Type header reflects the output format (e.g. image/webp).

  Payment Required (402) — L402 flow:
    {
      "error": "Payment required.",
      "payment_type": "lightning_l402",
      "invoice": {
        "id":             "<64-char payment_hash hex>",
        "bolt11":         "lnbc...",
        "amount_usd":     "0.05",
        "amount_msat":    5000000,
        "tokens_granted": 1,
        "expires_at":     "2026-04-03T21:00:00.000Z"
      },
      "instructions": [
        "1. Pay the bolt11 Lightning invoice using any Lightning wallet.",
        "2. Retry your request with: Authorization: L402 <payment_hash>:<payment_preimage>"
      ]
    }

  Forbidden (403) — free-tier API key blocked:
    {
      "error": "API access requires a Pro or Business plan.",
      "message": "Free accounts can use all tools through the web UI at vaultforge.work. Upgrade to Pro ($3.99/mo) or Business ($9.99/mo) to enable API key access.",
      "upgrade_url": "https://vaultforge.work/pricing",
      "l402_info": "For pay-per-request access with no subscription, omit the X-API-Key header and follow the L402 Lightning flow."
    }

  Unauthorized (401):
    { "error": "Authentication required.", "hint": "...", "docs": "https://vaultforge.work/api-docs" }

  Method Not Allowed (405 on GET for POST endpoints):
    { "error": "Method Not Allowed — GET is not supported on this endpoint.", "endpoint": "...", "method": "POST", ... }

---

## Pricing

  L402 pay-per-request (no account, Lightning only):
    convert / compress-image / compress-pdf / exif-remove / images-to-pdf: ~$0.05 per request
    ocr / merge: ~$0.10 per request
    pii-redact: ~$0.15 per request
    bg-remove / upscale: ~$0.25 per request
    doc-to-markdown: ~$0.20–$1.20 (tiered by file size, 4–24 tokens)
    tokens/lightning-topup: $0.03 per token (pay via L402, session-scoped)

  Token packs (buy in bulk with Stripe, for API key users):
    Basic:    100 tokens  — $2.99
    Standard: 500 tokens  — $9.99
    Pro:     2000 tokens  — $29.99

  Subscriptions (required for API key access):
    Pro:      $3.99/month  — 500 tokens/mo, 20 conversions/day, all Pro features + API access
    Business: $9.99/month  — 2000 tokens/mo, unlimited conversions, all features + API access

  Free tier (web UI only — no API access):
    All tools available at https://vaultforge.work after creating an account.
    3–5 conversions/day depending on tool, no API key access.

---

## Minimal L402 Test (Python, no account needed)

  import requests, hashlib

  BASE = "https://vaultforge.work/api/v1"

  # Smallest test: convert a tiny PNG to JPEG
  tiny_png = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd8N\x00\x00\x00\x00IEND\xaeB`\x82'

  # Step 1 — trigger 402
  r = requests.post(f"{BASE}/convert",
      files={"file": ("test.png", tiny_png, "image/png")},
      data={"to": "jpeg"})

  assert r.status_code == 402, f"Expected 402, got {r.status_code}"
  body = r.json()
  payment_hash = body["invoice"]["id"]
  bolt11 = body["invoice"]["bolt11"]
  print(f"Pay: {bolt11}")
  preimage = input("Preimage (64-char hex from wallet): ").strip()

  # Optional verification
  assert hashlib.sha256(bytes.fromhex(preimage)).hexdigest() == payment_hash, "Bad preimage"

  # Step 2 — retry with proof
  r2 = requests.post(f"{BASE}/convert",
      headers={"Authorization": f"L402 {payment_hash}:{preimage}"},
      files={"file": ("test.png", tiny_png, "image/png")},
      data={"to": "jpeg"})

  assert r2.status_code == 200, f"Error: {r2.status_code} {r2.text}"
  open("result.jpg", "wb").write(r2.content)
  print("Done — saved as result.jpg")

---

## Notes for AI Agents

- All file uploads must use multipart/form-data (not JSON, not base64).
- Multiple-file endpoints use the field name "files" (not "file").
- The /api/v1/convert endpoint streams the file directly; other endpoints return JSON with a downloadUrl.
- Download URLs at /api/store/* are valid for 30 minutes and require no auth.
- The L402 payment_hash is NOT a URL — it is the raw 64-character hex payment hash.
- Once an L402 token is verified, it can be reused for 24 hours with the same payment_hash:preimage pair.
- Free accounts are blocked at the API layer (HTTP 403). Use L402 for pay-per-request without a subscription.
- API key holders on Pro/Business get a daily quota before tokens are deducted; L402 always deducts tokens.
- The cheapest operation is any single-file conversion (convert, compress, exif-remove) at ~$0.05 or 1 token.