VaultForge API — Agent Guide ============================= https://vaultforge.work | Last-Updated: 2026-04-03 This plain-text guide is designed for AI agents, crawlers, and automated tools. No JavaScript required. Start here: Site-wide agent guide: GET https://vaultforge.work/llms.txt OpenAPI 3.0 spec : GET https://vaultforge.work/api/v1/openapi.json AI plugin JSON : GET 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: Method A — API Key (Pro or Business plan required): Header: X-API-Key: Requires an active Pro ($3.99/mo) or Business ($9.99/mo) subscription. Free accounts will receive HTTP 403. Upgrade at: https://vaultforge.work/pricing Get a key at: https://vaultforge.work/api-docs Method B — L402 Lightning (no account required, pay-per-request): The simplest path for agents and automation — no signup, no subscription. 1. Make your API request with NO auth header. Server returns HTTP 402 with a BOLT11 Lightning invoice. 2. Pay the BOLT11 invoice with any Lightning wallet (Alby, Phoenix, Breez, Zeus, Mutiny…). After payment your wallet shows the 64-char hex "payment preimage". 3. Retry the SAME request with: Authorization: L402 : Where payment_hash = the "id" field from the 402 response invoice object. The token is valid for 24 hours after first use. 402 RESPONSE BODY ----------------- { "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-03-28T21:00:00.000Z" } } ENDPOINTS --------- GET /api/v1/openapi.json — Full OpenAPI 3.0 spec (no auth) GET /api/v1/me — Account info (API key or L402 session) GET /api/v1/history — Conversion history (API key required; L402 returns empty) GET /api/agent-guide — This guide (no auth) POST /api/v1/tokens/lightning-topup — Pre-fund a session with Lightning (no account required) JSON body fields: tokens optional how many tokens to purchase (1-1000, default 10) Pricing: $0.03 per token (~3 sats each at current rates) Flow: 1. POST /tokens/lightning-topup (no auth) → receive 402 with BOLT11 invoice 2. Pay invoice → get payment preimage from wallet 3. Retry POST /tokens/lightning-topup with: Authorization: L402 : 4. Receive: { success: true, tokens_granted: N, message: "..." } HOW TO USE THE TOKENS: The same "Authorization: L402 :" header from step 3 is your session credential. Use it unchanged on every subsequent API call for the next 24 hours. No new 402 invoice will be issued — the server sees the credential is already paid and grants access immediately. Example (after topup): curl -X POST https://vaultforge.work/api/v1/compress-image -H "Authorization: L402 :" -F "file=@photo.jpg" curl -X POST https://vaultforge.work/api/v1/ocr -H "Authorization: L402 :" -F "file=@scan.pdf" The credential works on ALL endpoints until it expires (24 h from first use). POST /api/v1/tokens/buy — Get a checkout URL to buy a permanent token pack (no account required) JSON body fields: pack REQUIRED "basic" | "standard" | "pro" Packs: basic → 100 tokens $2.99 standard → 500 tokens $9.99 pro → 2000 tokens $29.99 Response: { checkoutUrl, tokens, price_usd, note } IMPORTANT: This endpoint returns a Stripe checkout URL — it does NOT purchase tokens directly. The user must visit the URL in a browser to complete payment. Agents cannot complete this flow. For autonomous token purchases use /tokens/lightning-topup instead. POST /api/v1/convert — Convert image format multipart/form-data fields: file REQUIRED image file (JPEG PNG WebP AVIF GIF BMP TIFF HEIC HEIF) to REQUIRED target format: jpeg | png | webp | avif | gif | bmp | tiff quality optional 1-100 (default 85) use_tokens optional "true" to spend tokens when daily limit is reached Response: binary file stream (Content-Type = output format) L402 cost: ~$0.05 / 1 token POST /api/v1/compress-image — Compress an image multipart/form-data fields: file REQUIRED JPEG PNG WebP TIFF HEIC quality optional 10-100 (default 80) output_format optional jpeg | png | webp | avif (default: jpeg) keep_metadata optional "true" to keep EXIF Response: JSON { fileId, filename, downloadUrl, savedPercent, tokensUsed } L402 cost (tiered by file size): < 2 MB → ~$0.05 / 1 token 2–10 MB → ~$0.10 / 2 tokens > 10 MB → ~$0.15 / 3 tokens POST /api/v1/compress-pdf — Compress a PDF multipart/form-data fields: file REQUIRED PDF file Response: JSON { fileId, filename, downloadUrl, savedPercent, tokensUsed } L402 cost (tiered by file size): < 2 MB → ~$0.05 / 1 token 2–10 MB → ~$0.10 / 2 tokens > 10 MB → ~$0.15 / 3 tokens POST /api/v1/merge — Merge 2-50 PDFs [Pro+ only] multipart/form-data fields: files REQUIRED 2-50 PDF files (field name is literally "files", NOT "files[]") password optional password to protect merged PDF Response: JSON { fileId, filename, downloadUrl, tokensUsed } L402 cost (tiered by file count): 1–5 files → ~$0.05 / 1 token 6–15 files → ~$0.10 / 2 tokens 16–30 files → ~$0.15 / 3 tokens 31–50 files → ~$0.20 / 4 tokens POST /api/v1/ocr — Extract text (OCR) multipart/form-data fields: file REQUIRED image or PDF lang optional language code (default: eng) Response: JSON { text, pages, confidence, tokensUsed } L402 cost (tiered by file size): < 2 MB → ~$0.10 / 2 tokens 2–10 MB → ~$0.15 / 3 tokens > 10 MB → ~$0.20 / 4 tokens POST /api/v1/pii-redact — Detect/redact PII [Pro+ only] Accepted file types: PDF (returns redacted PDF file via downloadUrl) | TXT (returns redacted text inline) WARNING: Images (.jpg/.png) are NOT accepted — you will receive 400. Only send PDF or TXT. multipart/form-data fields: file REQUIRED PDF or TXT file only use_tokens optional "true" to spend tokens Response: PDF input → JSON { fileId, filename, downloadUrl, totalRedacted, counts, tokensUsed } TXT input → JSON { redactedText, totalRedacted, counts, tokensUsed } L402 cost (tiered by file size): < 2 MB → ~$0.10 / 2 tokens 2–10 MB → ~$0.15 / 3 tokens > 10 MB → ~$0.20 / 4 tokens POST /api/v1/bg-remove — Remove image background [Business only] multipart/form-data fields: file REQUIRED JPEG PNG or WebP Response: JSON { fileId, filename, downloadUrl, tokensUsed } L402 cost: ~$0.25 / 5 tokens (flat — AI model cost is fixed per image) POST /api/v1/upscale — AI upscale [Business only] multipart/form-data fields: file REQUIRED JPEG PNG or WebP scale optional 2 or 4 (default 2) Response: JSON { fileId, filename, downloadUrl, tokensUsed } L402 cost (tiered by scale factor): scale=2 → ~$0.15 / 3 tokens scale=4 → ~$0.25 / 5 tokens POST /api/v1/images-to-pdf — Combine images into PDF multipart/form-data fields: files REQUIRED image files — JPEG, PNG, WebP, GIF, BMP, AVIF (field name is literally "files", NOT "files[]") Response: JSON { fileId, filename, downloadUrl, tokensUsed } L402 cost (tiered by image count): 1–3 images → ~$0.05 / 1 token 4–10 images → ~$0.10 / 2 tokens 11–25 images → ~$0.15 / 3 tokens 26–50 images → ~$0.20 / 4 tokens POST /api/v1/exif-remove — Strip EXIF metadata multipart/form-data fields: file REQUIRED image file Response: JSON { fileId, filename, downloadUrl, tokensUsed } L402 cost: ~$0.05 / 1 token POST /api/v1/doc-to-markdown — Convert document to AI-ready Markdown [Pro+ only] multipart/form-data fields: file REQUIRED PDF, DOCX, PPTX, XLSX, or HTML file use_tokens optional "true" to spend tokens when on free/lower tier Response: JSON { markdown, wordCount, charCount, tokensUsed } L402 cost (tiered by file size): < 1 MB → ~$0.05 / 1 token 1–10 MB → ~$0.10 / 2 tokens 10–50 MB → ~$0.20 / 4 tokens > 50 MB → ~$0.30 / 6 tokens DOWNLOAD FILES -------------- All JSON responses include a downloadUrl like: https://vaultforge.work/api/store// Download with a plain GET request — no auth required. Files expire after 30 minutes. MINIMAL PYTHON EXAMPLE (L402, no account) ------------------------------------------ import requests, hashlib BASE = "https://vaultforge.work/api/v1" 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\x60\x82' # Step 1 — trigger 402 r = requests.post(f"{BASE}/convert", files={"file": ("test.png", tiny_png, "image/png")}, data={"to": "jpeg"}) body = r.json() payment_hash = body["invoice"]["id"] bolt11 = body["invoice"]["bolt11"] # Step 2 — pay bolt11 with wallet, get preimage preimage = input(f"Pay: {bolt11}\nPreimage: ").strip() # Verify preimage locally assert hashlib.sha256(bytes.fromhex(preimage)).hexdigest() == payment_hash # Step 3 — retry with L402 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"}) open("result.jpg","wb").write(r2.content) print("Done:", r2.status_code) PRICING SUMMARY --------------- L402 per-request (all tiers, no account): Cheapest: convert / compress / exif-remove / images-to-pdf → ~$0.05 (~50 sats) Medium: ocr / merge / doc-to-markdown → ~$0.10 Premium: pii-redact → ~$0.15 | bg-remove / upscale → ~$0.25 Subscriptions (Stripe): Pro $3.99/month — 500 tokens, 20 conversions/day, merge unlocked Business $9.99/month — 2000 tokens, unlimited, all features Token packs (Stripe): Basic 100 tokens $2.99 Standard 500 tokens $9.99 Pro 2000 tokens $29.99 NOTES FOR AGENTS ---------------- - All file uploads MUST use multipart/form-data (NOT JSON, NOT base64). - Multi-file endpoints (merge, images-to-pdf) use field name "files" — NOT "files[]". Using "files[]" will cause a 500 "Unexpected field" error. The correct field name is exactly "files". - /api/v1/convert streams the output file directly. Other endpoints return JSON + downloadUrl. - Download URLs at /api/store/* need no auth and expire in 30 minutes. - L402 payment_hash is a raw 64-char hex string. preimage is also 64-char hex. - sha256(bytes.fromhex(preimage)).hexdigest() == payment_hash must hold. - Once verified, an L402 token (same payment_hash:preimage pair) works for 24 hours. FILE FORMAT REQUIREMENTS (critical — wrong type → instant 400): convert → JPEG PNG WebP AVIF GIF BMP TIFF HEIC (images only) compress-image → JPEG PNG WebP TIFF HEIC compress-pdf → PDF only merge → PDF only (min 2 files required) ocr → JPEG PNG WebP TIFF BMP GIF or PDF pii-redact → PDF or TXT only (images not supported → 400) bg-remove → JPEG PNG WebP only upscale → JPEG PNG WebP only images-to-pdf → JPEG PNG WebP GIF BMP AVIF (min 1 file, images only) doc-to-markdown → PDF DOCX PPTX XLSX HTML (NOT images) GENERATING VALID TEST FILES (Python): # Minimal valid PDF (1 page, ~300 bytes): pdf_bytes = b'%PDF-1.4\n1 0 obj\n<>\nendobj\n2 0 obj\n<>\nendobj\n3 0 obj\n<>\nendobj\nxref\n0 4\n0000000000 65535 f \n0000000009 00000 n \n0000000068 00000 n \n0000000125 00000 n \ntrailer\n<>\nstartxref\n232\n%%EOF' # Minimal valid PNG (10x10 red square, ~100 bytes): import struct, zlib def make_png(w=10, h=10): def chunk(t,d): c=struct.pack('>I',len(d))+t+d; return c+struct.pack('>I',zlib.crc32(t+d)&0xffffffff) raw=b''.join(b'\x00'+bytes([255,0,0]*w) for _ in range(h)) return b'\x89PNG\r\n\x1a\n'+chunk(b'IHDR',struct.pack('>IIBBBBB',w,h,8,2,0,0,0))+chunk(b'IDAT',zlib.compress(raw))+chunk(b'IEND',b'') png_bytes = make_png() # Minimal valid TXT (for pii-redact): txt_bytes = b'Contact: john.doe@example.com, Phone: 555-123-4567, SSN: 123-45-6789' CURL --OUTPUT WARNING --------------------- When using curl --output , curl writes the response body to disk regardless of the HTTP status code. A 402 or 403 response will save the JSON error to your file, not the actual document. Always verify the HTTP status: curl -X POST https://vaultforge.work/api/v1/images-to-pdf \ -H "X-API-Key: vf_live_your_key_here" \ -F "files=@page1.jpg" -F "files=@page2.jpg" \ --output merged.pdf \ --write-out "\nHTTP Status: %{http_code}\n" # HTTP Status: 200 → merged.pdf is a real PDF # HTTP Status: 402 → merged.pdf is a JSON payment challenge (not a PDF) # HTTP Status: 403 → merged.pdf is a JSON error (API key requires Pro/Business plan) To verify your API key is valid before processing files: curl -s -o /dev/null -w "%{http_code}" https://vaultforge.work/api/v1/me \ -H "X-API-Key: vf_live_your_key_here"