# Pufus API and Runtime Reference

> Polymorphic Luau virtualization and runtime defense powered by Mobius, our proprietary obfuscation technology.

## Hostnames
- REST API: https://api.pufus.win
- Public Script Delivery: https://script.pufus.win
- Shielded Proxy Network: https://proxy.pufus.win
- Developer Documentation: https://docs.pufus.win
- Machine Readable Index: https://docs.pufus.win/llms.txt

## Architecture and Proprietary Mobius Engine
Pufus is powered by Mobius, a proprietary Luau virtualization engine developed in-house. Every execution from script.pufus.win constructs a dynamic polymorphic binary with per build opcode mappings, randomized instruction set architecture, and stream encryption.

## Mandatory Server Execution Signature vs. Optional Runtime Integrity Check
Pufus operates two distinct runtime verification layers:
1. Mandatory Single-Use Execution Signature & 90s Time Limit: Enforced automatically by the server on all hosted scripts (Free, Pay-Per-Project, and Max). Every served build is signed with a server HMAC signature and a 90-second execution window. On startup, the script performs a server-side challenge against /v1/c?sig=... and burns the signature immediately so each generated build can only ever be executed once. Standalone scripts compiled via POST /api/obfuscate do not include this check so they can run locally.
2. Optional Runtime Integrity Check (integrity_check): Starts disabled (false) by default on every repository. When enabled by the owner, it injects additional anti-hook closure inspection (verifying pcall, tostring, string.byte, and HttpGet against Lua closure hooks) and validates the repository's live file state digest.

## Authentication and Key Management
Authenticate every call to api.pufus.win with a Bearer token in the Authorization header:
Authorization: Bearer <your_api_key>
- GET https://api.pufus.win/api/keys (List up to 3 active API keys)
- POST https://api.pufus.win/api/keys (Create key with body { "label": "name" })
- DELETE https://api.pufus.win/api/keys/<kid> (Revoke API key)

## Unified Quota, System Limits, and Team Roles
- POST /api/obfuscate: 12 scripts per minute (shared across all API keys on your account)
- General REST API: 60 requests per minute (shared across all API keys on your account)
- Max Script Size: 7 MB (7,340,032 bytes) per file, 8 MB max HTTP body
- Repository Limit: 100 repositories on Max Lifetime ($2), 1 free + $0.10/project on Standard
- Team Roles: owner (full control), editor (can manage files, licenses, and kick players), viewer (read-only)

## Endpoints

### Standalone Obfuscation
POST https://api.pufus.win/api/obfuscate
Body: { "code": "print('hello')", "is_module": false, "raw": false }
Returns JSON { "ok": true, "code": "..." } or plain text if raw is true or ?raw=1.

### Repositories
- GET https://api.pufus.win/api/projects (List all owned and shared repositories)
- POST https://api.pufus.win/api/projects (Create repository with { "name": "slug" })
- GET https://api.pufus.win/api/projects/<pcode> (Get repository details and file list with fid)
- PATCH https://api.pufus.win/api/projects/<pcode> (Update { "integrity_check": true, "licensing_enabled": true, "name": "slug" })
- DELETE https://api.pufus.win/api/projects/<pcode> (Delete repository and all encrypted files)

### Scripts and Modules
- POST https://api.pufus.win/api/projects/<pcode>/files (Upload script { "name": "main", "code": "...", "is_entry": true })
- GET https://api.pufus.win/api/projects/<pcode>/files/<fid> (Fetch decrypted script code)
- PUT https://api.pufus.win/api/projects/<pcode>/files/<fid> (Update script { "name": "main", "code": "...", "is_entry": true })
- DELETE https://api.pufus.win/api/projects/<pcode>/files/<fid> (Delete script from repository)

### Licensing System & HWID Lock
- PATCH https://api.pufus.win/api/projects/<pcode>/licensing (Toggle licensing with { "enabled": true })
- GET https://api.pufus.win/api/projects/<pcode>/licenses (List all license keys)
- POST https://api.pufus.win/api/projects/<pcode>/licenses (Issue 1-50 keys with charset, length, separator, chunk_size, prefix, duration, max_users 1-1000, hwid_lock (optional boolean, defaults to false), note, count)
- PATCH https://api.pufus.win/api/projects/<pcode>/licenses/<lid> (Update { "status": "paused" | "active" | "revoked", "max_users": 2, "hwid_lock": true | false, "reset_hwid": true })
- POST https://api.pufus.win/api/projects/<pcode>/licenses/<lid>/reset-hwid (Unbind and reset the locked HWID on a license key; pass { "disable_lock": true } to also turn off HWID lock)
- DELETE https://api.pufus.win/api/projects/<pcode>/licenses/<lid> (Delete license key)
- POST https://api.pufus.win/v1/license/validate (Public key validation with { "pcode": "...", "key": "...", "hwid": "..." })

### Live Telemetry
- GET https://api.pufus.win/api/projects/<pcode>/players (List active Roblox sessions)
- DELETE https://api.pufus.win/api/projects/<pcode>/players/<slot_id> (Disconnect active player session)

## Luau Runtime Loader and Executor Environment
- Licensed loader: loadstring(game:HttpGet("https://script.pufus.win/<pcode>?key=" .. key))()
- Path loader: loadstring(game:HttpGet("https://script.pufus.win/<pcode>/k=" .. key))()
- Open loader: loadstring(game:HttpGet("https://script.pufus.win/<pcode>"))()
- Virtual modules: require("module_name") resolves secondary repository files from memory with zero HTTP requests.
- Heartbeat tolerance: Pings every 15s via request/http_request/syn.request. Tolerates up to 4 missed pings (60s) for lag spikes, and frees inactive slots after 45s.
- HWID Authenticity: Server always validates that the client's HWID is genuine using entropy, pattern diversity, and C++ executor fingerprint headers.

## Compile-Time Placeholders, Conditionals, and Custom Guard Directives (Max Exclusive)
Max accounts can use placeholders inside Luau string literals (100% valid syntax in Roblox Studio). They are resolved and escaped before Mobius compiles the script, baking them into the encrypted constant pool:
- {{PUFUS_NOTE}}: Buyer note/tag on the license key (or guest)
- {{PUFUS_DISCORD}}: Discord user ID or tag extracted from buyer note if prefixed with discord:
- {{PUFUS_KEY}}: Active license key string
- {{PUFUS_HWID}}: Verified normalized 32-character HWID hash of the user (or unassigned)
- {{PUFUS_HWID_LOCKED}}: Boolean literal string (true or false) indicating if HWID lock is enabled on the key
- {{PUFUS_EXPIRES}}: Expiration date (YYYY-MM-DD HH:MM UTC or Lifetime)
- {{PUFUS_EXPIRES_TS}}: Expiration Unix timestamp in seconds (or 0 for Lifetime)
- {{PUFUS_HOURS_LEFT}}: Numeric hours remaining until expiration (0 for lifetime or expired)
- {{PUFUS_DAYS_LEFT}}: Numeric days remaining until expiration
- {{PUFUS_STATUS}}: Key status string (active, expired, or grace)
- {{PUFUS_IS_EXPIRED}}: Boolean literal string (true or false)
- {{PUFUS_IN_GRACE}}: Boolean literal string (true or false)
- {{PUFUS_SLOTS}}: Active slots vs max slots (e.g. 1/2)
- {{PUFUS_ONLINE}}: Current online players using this key
- {{PUFUS_MAX_USERS}}: Max concurrent users allowed on this key
- {{PUFUS_USES}}: Total validation count of this key
- {{PUFUS_PROJECT}}: Repository name
- {{PUFUS_CODE}}: 8-character repository code
- {{PUFUS_OWNER}}: Repository owner username
- {{PUFUS_RUNS}}: Total repository execution count
- {{PUFUS_BUILD_ID}}: Unique 12-char hex build ID per execution
- {{PUFUS_SERVER_TIME}}: Server UTC Unix timestamp at compilation
- {{PUFUS_SERVER_DATE}}: Server UTC date string at compilation
- {{IF_<COND>}}...{{ELSE}}...{{END_IF}}: Compile-time conditional preprocessor. Supports EXPIRED, NOT_EXPIRED, VALID, IN_GRACE, LIFETIME, HWID_LOCKED, and relational comparisons (HOURS_LEFT <= 24, ONLINE > 1, STATUS == grace)
- local PUFUS_ERROR_MSG = "...": Custom initial license error message (supports {{PUFUS_REASON}})
- local PUFUS_KICK_MSG = "...": Custom mid-game kick message (supports {{PUFUS_REASON}})
- local PUFUS_ON_INVALID = function(reason) ... end: Custom callback invoked on invalid license/auth failure before erroring/kicking
- local PUFUS_ON_EXPIRED = function(reason) ... end: Custom callback invoked when license expires or is revoked before kicking

## Complete Error Reference
- HTTP 400: Validation error (empty code, duplicate project/file name, or 3 API key limit reached).
- HTTP 401: Missing or invalid Bearer API key.
- HTTP 402: Insufficient balance ($0.10 required for additional repository on Standard plan).
- HTTP 403: Account suspended, Max plan required, 100 project limit reached, or viewer read-only role.
- HTTP 413: Script exceeds 7 MB or payload exceeds 8 MB.
- HTTP 429: Shared rate limit exceeded (check Retry-After header).
- HTTP 500: Luau syntax error failed AST/bytecode compilation.
- Runtime Loader & Signature Errors: Browser access detected or your executor does not support Pufus, Script time limit expired, Script already executed, Signature verification failed, Integrity check failed, Challenge verification failed, Script not found, Execution disabled, Missing license key, Invalid license key, No entrypoint script, Private script, Payload error, Compilation failed.
- License Errors: missing_key, invalid_key, license_paused, license_revoked, license_expired, hwid_mismatch, invalid_or_spoofed_hwid, missing_hwid, max_users_reached (X/Y), session_terminated_by_owner, key_changed_or_removed, heartbeat_timeout, key_rate_limited, requester_unavailable.