API Reference

Submit Python files for protection and retrieve compiled artifacts programmatically. All API endpoints are under /api/v1/ and require an API key.

Overview

The PyVMProtect API lets you integrate Python protection into your own build pipeline. The typical flow is:

1. Submit a .py or .zip file → receive a job_id
2. Poll the job status until status is complete or error
3. (Optional) Confirm Cython hot-paths if status reaches hot_path_pending
4. Download the protected artifact

Authentication

All /api/v1/ endpoints require an API key in the Authorization header:

Authorization: Bearer pvmp_your_api_key_here

To generate your API key, go to My Account and click Generate Key in the API Key section. Regenerating a key immediately invalidates the previous one.

Endpoints

{
  "job_id":      "a3f9bc12e4561234a3f9bc12e4561234",
  "status":      "queued",
  "module_name": "my_module",
  "is_zip":      false
}

{
  "job_id":         "a3f9bc12e4561234...",
  "status":         "building",
  "module_name":    "my_module",
  "is_zip":         false,
  "progress_pct":   45,
  "progress_label": "Compiling extensions",
  "created_at":     1713700000,
  "updated_at":     1713700042,

  // Present when status = "hot_path_pending":
  "functions":  ["encrypt_payload", "verify_license", "decode_config"],

  // Present when status = "complete":
  "download_token": "abc123..."
}

{
  "job_id":    "a3f9bc12e4561234...",
  "hot_paths": ["encrypt_payload", "verify_license"]
}

{ "ok": true, "job_id": "...", "hot_paths": ["encrypt_payload", "verify_license"] }

Full Workflow

The complete lifecycle of a build job:

POST /api/v1/job_submit.php          → { job_id }
  ↓
GET  /api/v1/job_status.php?job_id=  → status: queued
  ↓  (poll every 2s)
GET  /api/v1/job_status.php?job_id=  → status: building, progress_pct: 45
  ↓
GET  /api/v1/job_status.php?job_id=  → status: hot_path_pending, functions: [...]
  ↓  (optional — only if Cython is enabled)
POST /api/v1/job_hotpath.php         → { ok: true }
  ↓
GET  /api/v1/job_status.php?job_id=  → status: complete, download_token: "..."
  ↓
GET  /api/v1/job_download.php?job_id= → .zip download

Code Examples

curl

Note: The API blocks the default curl/* user-agent. Add -H "User-Agent: MyApp/1.0" (any non-curl UA) to all requests.

# 1. Submit a file
curl -X POST https://pyvmprotect.com/api/v1/job_submit.php \
  -H "Authorization: Bearer pvmp_your_key_here" \
  -H "User-Agent: MyApp/1.0" \
  -F "file=@my_script.py" \
  -F "module_name=my_module"

# 2. Poll status
curl https://pyvmprotect.com/api/v1/job_status.php?job_id=JOB_ID \
  -H "Authorization: Bearer pvmp_your_key_here" \
  -H "User-Agent: MyApp/1.0"

# 3. Download when complete
curl -O https://pyvmprotect.com/api/v1/job_download.php?job_id=JOB_ID \
  -H "Authorization: Bearer pvmp_your_key_here" \
  -H "User-Agent: MyApp/1.0"

Python

import time
import requests

API_KEY = "pvmp_your_key_here"
BASE    = "https://pyvmprotect.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Submit
with open("my_script.py", "rb") as f:
    resp = requests.post(
        f"{BASE}/job_submit.php",
        headers=HEADERS,
        files={"file": ("my_script.py", f, "text/x-python")},
        data={"module_name": "my_module"},
    )
resp.raise_for_status()
job_id = resp.json()["job_id"]
print(f"Job submitted: {job_id}")

# 2. Poll until done
while True:
    status = requests.get(
        f"{BASE}/job_status.php",
        headers=HEADERS,
        params={"job_id": job_id},
    ).json()

    s = status["status"]
    print(f"  {s} ({status.get('progress_pct', 0)}%)")

    if s == "hot_path_pending":
        # Confirm all suggested functions (or pass a subset)
        requests.post(
            f"{BASE}/job_hotpath.php",
            headers=HEADERS,
            json={"job_id": job_id, "hot_paths": status["functions"]},
        ).raise_for_status()

    elif s == "complete":
        break

    elif s == "error":
        raise RuntimeError(f"Build failed: {status.get('error')}")

    time.sleep(2)

# 3. Download
resp = requests.get(
    f"{BASE}/job_download.php",
    headers=HEADERS,
    params={"job_id": job_id},
)
resp.raise_for_status()
with open("my_module_protected.zip", "wb") as f:
    f.write(resp.content)
print("Downloaded: my_module_protected.zip")

Status Values

Rate Limits

When a rate limit or active-job limit is exceeded the API returns HTTP 429 with an error message. Retry after an existing build finishes or after the hourly window resets. Free accounts cannot use the API key endpoint — a Beta or Premium plan is required.

Errors

All errors return JSON with an error field:

{ "error": "Invalid API key" }