PHP API Documentation & Wrapper

Updated PHP API docs (2026)

This post replaces the old examples with the current, practical flow. The API now supports direct KV files, ZIP uploads/URLs (with extraction rules), and follow-up serial checks.

Auth

Use one of these (header preferred):

Authorization: Bearer YOUR_API_TOKEN
X-API-Token: YOUR_API_TOKEN
?api_token=YOUR_API_TOKEN

Endpoints

1) Validate local file

POST /api/?action=validate
Content-Type: multipart/form-data
file=@kv.bin

2) Validate remote file/ZIP

POST /api/?action=validate_url
Content-Type: application/x-www-form-urlencoded
url=https://example.com/kv.zip

3) Check serial / shared status

GET /api/?action=info&id=000000000000

4) Rarity lookup

GET /api/?action=rarity&date=01-15-09

ZIP behavior (important)

• ZIP is accepted for validate and validate_url.
• Exactly one valid 16KB KV must exist inside the ZIP.
• Nested folders are allowed.
• If multiple KV candidates exist, validation fails.

Typical response fields

{
  "success": true,
  "unbanned": true,
  "message": "KV is unbanned",
  "serial": "XXXXXXXXXXXX",
  "mfg_date": "MM-DD-YY",
  "region": "....",
  "drive_id": "...",
  "rarity": "...",
  "console": "...",
  "part_number": "...",
  "model_number": "...",
  "color": "#....",
  "extracted_from_zip": true,
  "kv_inner_path": "folder/kv.bin"
}

Production PHP example

<?php
final class UnsharedApi {
    private string $token;
    private string $base;

    public function __construct(string $token, string $base = "https://api.unshared.shop/api/") {
        $this->token = $token;
        $this->base = rtrim($base, "/") . "/";
    }

    private function request(string $method, string $query, array $headers = [], $post = null): array {
        $ch = curl_init($this->base . $query);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        if ($post !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
        $headers[] = "X-API-Token: " . $this->token;
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        $raw = curl_exec($ch);
        $http = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $err = curl_error($ch);
        curl_close($ch);
        if ($raw === false) return ["success" => false, "error" => $err ?: "curl_error"];
        $json = json_decode($raw, true);
        if (!is_array($json)) return ["success" => false, "error" => "invalid_json", "http" => $http, "raw" => $raw];
        $json["_http"] = $http;
        return $json;
    }

    public function validateFile(string $path): array {
        if (!is_file($path)) return ["success" => false, "error" => "file_not_found"];
        $post = ["file" => new CURLFile($path, "application/octet-stream", basename($path))];
        return $this->request("POST", "?action=validate", [], $post);
    }

    public function validateUrl(string $url): array {
        return $this->request("POST", "?action=validate_url", ["Content-Type: application/x-www-form-urlencoded"], http_build_query(["url" => $url]));
    }

    public function checkSerial(string $serial): array {
        return $this->request("GET", "?action=info&id=" . urlencode($serial));
    }
}

$api = new UnsharedApi("YOUR_TOKEN");
$res = $api->validateFile(__DIR__ . "/kv.bin");
if (!empty($res["success"])) {
    echo "Status: " . ($res["status"] ?? "Unknown") . PHP_EOL;
    if (!empty($res["serial"])) {
        $check = $api->checkSerial($res["serial"]);
        // optional secondary check
    }
} else {
    echo "Error: " . ($res["error"] ?? $res["message"] ?? "unknown");
}
?>

Best practices

• Always verify file size (16KB for raw KV) before upload.
• Treat network/JSON failures as retryable.
• Log the raw response when debugging parser issues.
• Don't hardcode tokens in public repos.
• Use serial info check after validation when needed.

Need help? Open a support ticket.