{"openapi":"3.0.3","info":{"title":"VaultForge API","version":"1.0.0","description":"Full-featured file processing API for developers and AI agents. Supports image conversion, compression, PDF merge, OCR, PII redaction, background removal, upscaling, and more. Auth: API key (X-API-Key header) or L402 Lightning (powered by Alby Hub via NWC). All processing is ephemeral — files expire in 30 minutes. Zero cloud storage.","contact":{"name":"VaultForge","url":"https://vaultforge.work/api-docs"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://vaultforge.work/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"L402Auth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Generate an API key at vaultforge.work/api-docs"},"L402Auth":{"type":"http","scheme":"bearer","bearerFormat":"L402","description":"L402 Lightning payment auth. Format: L402 <macaroon>:<preimage>."}}},"paths":{"/me":{"get":{"summary":"Account status","description":"Returns your tier, token balance, daily usage, and API key info.","operationId":"getMe","responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"tier":{"type":"string","enum":["free","pro","business"]},"tokenBalance":{"type":"integer"},"dailyConversionsUsed":{"type":"integer"},"dailyLimit":{"type":"integer"},"apiKeyPrefix":{"type":"string"}}}}}},"401":{"description":"Unauthorized"}}}},"/convert":{"post":{"summary":"Convert image format","description":"Convert images between formats. Supported inputs: JPEG, PNG, WebP, AVIF, GIF, BMP, TIFF, HEIC. Cost: 2 tokens (or 1 daily quota slot).","operationId":"convertImage","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","to"],"properties":{"file":{"type":"string","format":"binary","description":"Input image file"},"to":{"type":"string","description":"Target format: jpeg, png, webp, avif, gif, bmp, tiff"},"quality":{"type":"integer","minimum":1,"maximum":100,"description":"Output quality 1-100 (default 85)"},"use_tokens":{"type":"string","enum":["true","false"],"description":"Spend tokens to bypass daily limit"}}}}}},"responses":{"200":{"description":"Converted file (binary stream, streamed directly)","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid format or unsupported conversion"},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}}}}},"/compress-image":{"post":{"summary":"Compress an image","description":"Reduce image file size with configurable quality. Output formats: jpeg, png, webp, avif (avif = Pro+). Cost: 3 tokens (or 1 daily quota slot).","operationId":"compressImage","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Input image (JPEG, PNG, WebP, TIFF, HEIC)"},"quality":{"type":"integer","minimum":10,"maximum":100,"description":"Quality 10-100 (default 80)"},"output_format":{"type":"string","description":"Output format: jpeg, png, webp, avif (default: jpeg)"},"keep_metadata":{"type":"string","enum":["true","false"],"description":"Preserve EXIF metadata (default false)"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Compressed image info + download link","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FileResponse"}],"properties":{"compressedSize":{"type":"integer"},"savedPercent":{"type":"integer","description":"Percentage size reduction"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}}}}},"/compress-pdf":{"post":{"summary":"Compress a PDF","description":"Reduce PDF file size by re-streaming with object compression. Cost: 3 tokens (or 1 daily quota slot).","operationId":"compressPdf","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Input PDF file"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Compressed PDF info + download link","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FileResponse"}],"properties":{"compressedSize":{"type":"integer"},"savedPercent":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}}}}},"/merge":{"post":{"summary":"Merge PDFs (Pro+)","description":"Merge multiple PDF files into one. Up to 20 files for Pro, 50 for Business. Optionally password-protect the merged output. Requires Pro plan or tokens. Cost: 5 tokens.","operationId":"mergePdfs","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"2-50 PDF files"},"password":{"type":"string","description":"Optional password to protect the merged PDF"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Merged PDF info + download link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileResponse"}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}},"403":{"description":"Tier insufficient — requires Pro or higher"}}}},"/ocr":{"post":{"summary":"Extract text via OCR (Pro+)","description":"Extract text from images or scanned PDFs using Tesseract OCR. Supported inputs: JPEG, PNG, WebP, TIFF, BMP, GIF, PDF. Returns extracted text inline (JSON). Requires Pro plan or tokens. Cost: 8 tokens.","operationId":"ocrExtract","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Image or PDF to extract text from"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Extracted text (returned inline, no download needed)","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Extracted plain text"},"charCount":{"type":"integer"},"lineCount":{"type":"integer"},"tokensUsed":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}},"403":{"description":"Tier insufficient — requires Pro or higher"}}}},"/doc-to-markdown":{"post":{"summary":"Document to AI-ready Markdown (Pro+)","description":"Convert PDF, DOCX, PPTX, XLSX, or HTML documents into clean, structured Markdown optimised for LLMs and RAG pipelines. Preserves headings, tables, lists, and code blocks. Powered by PyMuPDF4LLM (PDFs) and MarkItDown (Office/HTML). Returns Markdown inline — no download needed. Requires Pro plan or tokens. Cost: 4 tokens (<1 MB) · 8 tokens (1–10 MB) · 16 tokens (10–50 MB) · 24 tokens (>50 MB).","operationId":"docToMarkdown","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PDF, DOCX, PPTX, XLSX, or HTML file"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Markdown content returned inline (no download needed)","content":{"application/json":{"schema":{"type":"object","properties":{"markdown":{"type":"string","description":"Clean Markdown representation of the document"},"wordCount":{"type":"integer","description":"Approximate word count of the Markdown output"},"charCount":{"type":"integer","description":"Character count of the Markdown output"},"tokensUsed":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}},"403":{"description":"Tier insufficient — requires Pro or higher"},"503":{"description":"Document conversion service temporarily unavailable"}}}},"/pii-redact":{"post":{"summary":"Redact PII (Pro+)","description":"Detect and redact personally identifiable information: emails, phone numbers, SSNs, credit cards, IPs. PDF input: visual black-box redaction (returned as file). TXT input: redacted text returned inline. Requires Pro plan or tokens. Cost: 12 tokens.","operationId":"piiRedact","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PDF or TXT file to redact"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Redaction results. PDF → download link. TXT → inline redacted text.","content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string"},"downloadUrl":{"type":"string"},"redactedText":{"type":"string","description":"For TXT input: redacted content inline"},"totalRedacted":{"type":"integer"},"counts":{"type":"object","description":"Counts per PII type detected"},"tokensUsed":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}},"403":{"description":"Tier insufficient — requires Pro or higher"}}}},"/bg-remove":{"post":{"summary":"Remove image background (Business)","description":"AI-powered background removal. Outputs a transparent PNG. Accepted inputs: JPEG, PNG, WebP. Requires Business plan or tokens. Cost: 25 tokens.","operationId":"bgRemove","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, or WebP image"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Transparent PNG download link","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FileResponse"}],"properties":{"outputSize":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}},"403":{"description":"Tier insufficient — requires Business"}}}},"/upscale":{"post":{"summary":"Upscale image 2× or 4× (Business)","description":"High-fidelity image enlargement using Lanczos3 algorithm with edge sharpening. Accepted inputs: JPEG, PNG, WebP. Scale: 2 (default) or 4. Requires Business plan or tokens. Cost: 15 tokens.","operationId":"upscaleImage","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, or WebP image"},"scale":{"type":"integer","enum":[2,4],"description":"Upscale factor: 2 or 4 (default 2)"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"Upscaled image download link","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FileResponse"}],"properties":{"scale":{"type":"integer"},"originalWidth":{"type":"integer"},"originalHeight":{"type":"integer"},"newWidth":{"type":"integer"},"newHeight":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}},"403":{"description":"Tier insufficient — requires Business"}}}},"/images-to-pdf":{"post":{"summary":"Convert images to PDF","description":"Combine one or more images into a single PDF. Accepted inputs: JPEG, PNG, WebP, GIF, BMP, AVIF, HEIC, DNG. Free: 2 images, Pro: 10 images, Business: 50 images (tokens expand limit). Cost: 4 tokens.","operationId":"imagesToPdf","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Image files (JPEG, PNG, WebP, etc.)"},"use_tokens":{"type":"string","enum":["true","false"]}}}}}},"responses":{"200":{"description":"PDF download link","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FileResponse"}],"properties":{"pageCount":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Daily limit reached or tier gate — provide use_tokens=true to spend tokens instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tokenCost":{"type":"integer","description":"Tokens required to proceed"},"tokenBalance":{"type":"integer","description":"Your current token balance"},"reason":{"type":"string","enum":["daily_limit","tier_gate","file_size"]}}}}}}}}},"/exif-remove":{"post":{"summary":"Strip EXIF metadata","description":"Remove all EXIF, XMP, and IPTC metadata from images. Free for all tiers — no daily quota consumed. Accepted inputs: JPEG, PNG, WebP, TIFF, HEIC.","operationId":"exifRemove","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Image file to strip metadata from"}}}}}},"responses":{"200":{"description":"Clean image download link","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FileResponse"}],"properties":{"outputSize":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/history":{"get":{"summary":"Conversion history","description":"Returns your last N API conversions. Requires an API key (L402 sessions have no history).","operationId":"getHistory","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":20,"maximum":100}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Conversion history","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sourceFilename":{"type":"string"},"sourceFormat":{"type":"string"},"targetFormat":{"type":"string"},"tokensUsed":{"type":"integer"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}}},"/tokens/buy":{"post":{"summary":"Buy tokens via Stripe","description":"Returns a Stripe checkout URL for purchasing a token pack.","operationId":"buyTokens","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pack"],"properties":{"pack":{"type":"string","enum":["basic","standard","pro"],"description":"basic=100 tokens ($2.99), standard=500 ($9.99), pro=2000 ($29.99)"}}}}}},"responses":{"200":{"description":"Stripe checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri"},"tokens":{"type":"integer"},"price_usd":{"type":"string"}}}}}},"401":{"description":"Unauthorized"}}}},"/tokens/lightning-topup":{"post":{"summary":"Top up tokens via Lightning (L402 — Alby Hub)","operationId":"lightningTopup","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tokens"],"properties":{"tokens":{"type":"integer","minimum":1,"description":"Number of tokens to buy (~$0.03/token)"}}}}}},"responses":{"402":{"description":"L402 invoice (pay with Lightning wallet)"},"502":{"description":"Alby Hub unreachable"}}}}}}