Bogachyov Ledger — API Reference

🔑 Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header. Obtain your key from the Bogachyov Ledger dashboard after purchasing a plan.

HTTP HEADER

Authorization: Bearer YOUR_API_KEY

⚠ Never expose your API key in client-side code or public repositories. Store it in environment variables on your server only.

🌐 Base URL

Production https://your-domain.replit.app/api

Replace your-domain.replit.app with your actual deployment domain. All API paths are prefixed with /api.

📡 Endpoint: Verify Media

POST /api/v1/media/verify

Upload an image file to run the full AI pipeline: perceptual hash comparison against the ledger database, three-zone classification, and optional auto-registration of unique originals.

Request Headers

Header	Value	Required
Authorization	Bearer <YOUR_API_KEY>	Yes
Content-Type	multipart/form-data	Yes

Request Body — Multipart Form Data

Field	Type	Required	Description
media_file	File (image/*)	Yes	Image file to verify. Accepted: JPEG, PNG, WEBP, GIF, BMP. Max size: 5 MB.

🚦 Similarity Zones

Every upload is classified into one of three zones based on its perceptual similarity to content already in the ledger.

ORIGINAL

similarity < 75%

ALLOW

Content is unique. Auto-registered in the ledger as an original asset. Returns the perceptual hash.

SUSPICIOUS

75% ≤ similarity ≤ 92%

BLOCK_AND_FLAG

High similarity detected. Upload blocked. Flagged for your platform's manual moderation queue. HTTP 409.

DEEPFAKE / THEFT

similarity > 92%

BAN

Critical match. Potential copyright theft or deepfake. Upload hard-blocked. HTTP 403. Recommended action: ban user.

📄 JSON Response Examples

200 OK — ALLOW (unique original)

JSON

{
  "match_found":          false,
  "status":               "ORIGINAL",
  "similarity_percentage": 12.4,
  "recommended_action":   "ALLOW",
  "hash":                  "a3b8c4d1e2f567890abc...",
  "file_name":             "product_photo.jpg",
  "message":              "Asset is unique. Registered as original in the ledger."
}

409 Conflict — BLOCK_AND_FLAG (high similarity)

JSON

{
  "match_found":             true,
  "status":                  "SUSPICIOUS",
  "similarity_percentage":    84.7,
  "structural_similarity":    79.2,
  "recommended_action":      "BLOCK_AND_FLAG",
  "matched_file":             "original_model_photo.jpg",
  "message":                 "High visual similarity detected. Flagged for manual moderation."
}

403 Forbidden — BAN (deepfake / copyright theft)

JSON

{
  "match_found":             true,
  "status":                  "DEEPFAKE_OR_THEFT",
  "similarity_percentage":    97.3,
  "structural_similarity":    95.8,
  "recommended_action":      "BAN",
  "matched_file":             "source_content.jpg",
  "message":                 "Critical similarity detected. Potential deepfake or copyright theft."
}

⚠ Error Codes

Status	Error	Description
200 OK	ORIGINAL	Unique asset. Registered and returned with hash.
401	Unauthorized	Missing or invalid Bearer token.
400	Bad Request	No `media_file` field in the request body.
409 Conflict	SUSPICIOUS	Similarity 75–92%. Upload blocked. Flag for review.
403 Forbidden	DEEPFAKE_OR_THEFT	Similarity >92%. Hard block. Ban recommended.
415	Unsupported Media Type	File is not a recognized image format.
500	Internal Server Error	Unexpected server error. Contact support.

💻 Code Examples

Copy-paste integration examples. Replace YOUR_API_KEY and your-domain.replit.app with your actual values.

JAVASCRIPT (NODE.JS)

// npm install form-data node-fetch
const FormData = require('form-data');
const fs       = require('fs');
const fetch    = require('node-fetch');

const API_KEY  = 'YOUR_API_KEY';
const BASE_URL = 'https://your-domain.replit.app/api';

async function verifyMedia(filePath) {
  const form = new FormData();
  form.append('media_file', fs.createReadStream(filePath));

  const response = await fetch(`${BASE_URL}/v1/media/verify`, {
    method:  'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      ...form.getHeaders(),
    },
    body: form,
  });

  const result = await response.json();

  switch (result.recommended_action) {
    case 'BAN':
      console.error('BANNED — deepfake or theft:', result.message);
      await banUser(userId); // your platform logic
      break;

    case 'BLOCK_AND_FLAG':
      console.warn('FLAGGED — similarity:', result.similarity_percentage + '%');
      await sendToModerationQueue(userId, result); // your platform logic
      break;

    default:
      console.log('APPROVED — hash:', result.hash);
  }

  return result;
}

verifyMedia('./upload.jpg').catch(console.error);

PYTHON

# pip install requests
import requests

API_KEY  = "YOUR_API_KEY"
BASE_URL = "https://your-domain.replit.app/api"

def verify_media(file_path: str) -> dict:
    headers = {"Authorization": f"Bearer {API_KEY}"}

    with open(file_path, "rb") as f:
        files    = {"media_file": (file_path, f, "image/jpeg")}
        response = requests.post(
            f"{BASE_URL}/v1/media/verify",
            headers=headers,
            files=files,
        )

    result = response.json()
    action = result.get("recommended_action")

    if action == "BAN":
        raise PermissionError(f"Banned: {result['message']}")

    elif action == "BLOCK_AND_FLAG":
        print(f"Flagged — {result['similarity_percentage']}% similarity")
        send_to_moderation_queue(result)  # your platform logic

    else:
        print(f"Approved — hash: {result['hash']}")

    return result


# Usage
try:
    data = verify_media("./upload.jpg")
    print(data)
except PermissionError as e:
    print("Access denied:", e)

Media Verification API