QuDEFENSE API Walkthrough

This guide walks new users through interacting with the QuDEFENSE API step-by-step using Python. For more detailed information on the API endpoints, parameters and return values, see the QuDEFENSE Endpoint Documentation.

All requests require the following HTTP headers:

qudefense-client-id: your_client_id_here
qudefense-secret-access-key: your_secret_access_key_here

/v1/ (Connection Test)

This verifies that the API is reachable and your authentication headers are working.

Python Example

import requests

headers = {
    "qudefense-client-id": "your_client_id_here",
    "qudefense-secret-access-key": "your_secret_access_key_here"
}

response = requests.get("https://sandbox.qudefense.com/v1/", headers=headers)
print(response.json())

Example Response

{'msg': "Congratulations!  You've connected to the QuDefense Core API"}

/v1/files/fingerprint

This endpoint computes a SHA-256 fingerprint and metadata hash for a file at the given S3 URL and logs that fingerprint on the Algorand blockchain. It is important to retain the returned `file_id` as you will use that everything time you verify the fingerprint of a file on the blockchain.

Python Example


s3 = boto3.client("s3")
url = s3.generate_presigned_url("get_object", Params={
    "Bucket": "qudefense-api-test",
    "Key": "api-test/files/QuDEFENSE-Test.pdf"
}, ExpiresIn=86400)

headers = {
    "qudefense-client-id": "your_client_id_here",
    "qudefense-secret-access-key": "your_secret_access_key_here"
}

payload = {
    "s3_presigned_url": url,
    "tags": {
        "User": "Mike",
        "Department": "IT"
    }
}
response = requests.post("https://sandbox.qudefense.com/v1/files/fingerprint", json=payload, headers=headers)
print(response.json())

Example Response

{
  "status": "success",
  "fingerprint": "26a226443e5fca0d48977ef23f3ce315feea9ab07eb3b20f4e27c7d7ae8c27e2",
  "metadata_hash": "3a0dea7c5f969a72791a39f6b7c90a2221eed07ff752fbec42b7513ece7d6cbe",
  "file_metadata": {
    "file_name": "QuDEFENSE-Test.pdf",
    "modified_date": "2025-04-24T19:11:18+00:00",
    "file_type": "application/pdf"
  },
  "blockchain_app_id": "738192992",
  "blockchain_txid": "357UJ34CDHJSJI5IDIKEHUZD4YQLZDNDVQBOZKTRWXNGHWTVKJMQ",
  "file_id": "fcd3da04-6b2e-441b-894a-de621da7f304"
}

/v1/files/verify-fingerprint

Verifies the fingerprint of a file against the Algorand blockchain. It takes the `file_id` that was returned by the /v1/files/fingerprint endpoint. Requires a presigned URL to the file.

Python Example


import boto3, requests

s3 = boto3.client("s3")
url = s3.generate_presigned_url("get_object", Params={
    "Bucket": "qudefense-api-test",
    "Key": "api-test/files/QuDEFENSE-Test.pdf"
}, ExpiresIn=86400)

headers = {
    "qudefense-client-id": "your_client_id_here",
    "qudefense-secret-access-key": "your_secret_access_key_here"
}

payload = {
    "s3_presigned_url": url,
    "file_id": "fcd3da04-6b2e-441b-894a-de621da7f304",
    "tags": {
        "User": "Soumya",
        "Department": "Development"
    }
}

response = requests.post("https://sandbox.qudefense.com/v1/files/verify-fingerprint", json=payload, headers=headers)
print(response.json())

Example Response - matching fingerprint

{
  "fingerprint_verify_result": "MATCH",
  "fingerprint": "26a226443e5fca0d48977ef23f3ce315feea9ab07eb3b20f4e27c7d7ae8c27e2",
  "bytes_processed": 13562,
  "blockchain_app_id": "738203414",
  "blockchain_txid": "UHVYJ7ADPL2TTPMOAYDOQLCTX67EGFRBCJA5BDRST5U7CWWE223Q",
  "file_id": "fcd3da04-6b2e-441b-894a-de621da7f304"
}

Example Response - mismatched fingerprint

{
  "fingerprint_verify_result": "MISMATCH",
  "fingerprint": "01a83ae75a04efdfe7f7c5ae7ee56f4f6309ac2c60276b91719e3db4899cff1f",
  "bytes_processed": 14061,
  "blockchain_app_id": "738203414",
  "blockchain_txid": "UHVYJ7ADPL2TTPMOAYDOQLCTX67EGFRBCJA5BDRST5U7CWWE223Q",
  "file_id": "fcd3da04-6b2e-441b-894a-de621da7f304"
}

/v1/files/{file_id}

Fetch a detailed report for a file by its `file_id`.

Python Example


import requests

headers = {
    "qudefense-client-id": "your_client_id_here",
    "qudefense-secret-access-key": "your_secret_access_key_here"
}

file_id = "34902c66-822c-4c42-bcfd-7875a0d5aee4"
url = f"https://sandbox.qudefense.com/v1/files/{file_id}"

response = requests.get(url, headers=headers)
print(response.json())

Example Response

{
  "file_id": "34902c66-822c-4c42-bcfd-7875a0d5aee4",
  "file_name": "s3_upload_and_return_presigned_url.py",
  "file_path": "owfwsohe/ynsvxtad/s3_upload_and_return_presigned_url.py",
  "file_size": 10627,
  "storage_provider": "AWS-S3",
  "storage_bucket_name": "api-teste-qudefense",
  "fingerprint_requested_datetime": "2025-04-21T04:10:09",
  "fingerprint_start_datetime": "2025-04-21T04:10:09",
  "fingerprint_complete_datetime": "2025-04-21T04:10:10",
  "blockchain_provider": "ALGORAND",
  "blockchain_app_id": 738209906,
  "api_client_id": "qudefense-outlook-api",
  "tags": {
    "Department": "IT",
    "User": "John"
  },
  "fingerprint_verification_history": [
    {
      "created_at": "2025-04-21T04:10:19",
      "fingerprint_verify_result": "MATCH",
      "tags": {
        "Office": "Toronto",
        "User": "Mike"
      }
    }
  ]
}

/v1/files/{file_id}/blockchain-history

Returns the blockchain verification history for a file, given it's `file_id`.

Python Example

import requests

headers = {
    "qudefense-client-id": "your_client_id_here",
    "qudefense-secret-access-key": "your_secret_access_key_here"
}

file_id = "71d548fd-95bb-4529-8378-e0a70079d487"
url = f"https://sandbox.qudefense.com/v1/files/{file_id}/blockchain-history"

response = requests.get(url, headers=headers)
print(response.json())

Example Response

{
   "app_id":738209906,
   "contract_info":{
      "creator_address":"7O2B7WCVHUSB3LQYRNBJ2JM5IM7HMAEZ4BXI4NTJMBVFWVEONVHCSZOUDA",
      "created_at":"2025-04-21 04:10:11",
      "creation_transaction_id":"46HZS3J3LCW5WF3QBEXWACFM64NHTNN3KUN7WFABC35XGDXZPCCA",
      "is_deleted":false
   },
   "global_state":{
      "fh":"ccb9e1c8c2344f2b7c0d752d1364863d3e5b058ebcb0a3b555f7b7a4bc54a207",
      "mh":"f25d5a62544c6ee982ae6719783b33493a10d116fda58e6eeadd85a05b444b05"
   },
   "verification_history":[
      {
         "id":"HDWRPNKMBSYPW3NBTNKBDDTL7PNSYPK6FBVEVNFGHVPSEIHEE7PA",
         "timestamp":1745554216,
         "result":"MATCH",
         "attempted_hash":"ccb9e1c8c2344f2b7c0d752d1364863d3e5b058ebcb0a3b555f7b7a4bc54a207",
         "transaction_id":"HDWRPNKMBSYPW3NBTNKBDDTL7PNSYPK6FBVEVNFGHVPSEIHEE7PA"
      }
   ]
}

/v1/files/search

Search for files with filters like date range, tags, and sort order.

Python Example

import requests

headers = {
    "qudefense-client-id": "your_client_id_here",
    "qudefense-secret-access-key": "your_secret_access_key_here"
}

params = {
    "start_date": "2025-04-01",
    "end_date": "2025-06-01",
    "date_type": "fingerprint",
    "verified_at_least_once": "true",
    "tag_key": "User",
    "tag_value": "Henry",
    "page": 1,
    "page_size": 20,
    "sort_order": "FINGERPRINT_DATE_DESC"
}

response = requests.get("https://sandbox.qudefense.com/v1/files/search", headers=headers, params=params)
print(response.json())

Example Response

{
  "files": [
    {
      "file_id": "1057610f-31f2-4461-86f9-5a7c53cd3bd9",
      "file_name": "s3_upload_and_return_presigned_url.py",
      "file_path": "qnseelnx/rpjtybvh/s3_upload_and_return_presigned_url.py",
      "file_size": 10628,
      "storage_provider": "AWS-S3",
      "storage_bucket_name": "api-test-qudefense",
      "fingerprint_requested_datetime": "2025-04-21T04:38:47",
      "fingerprint_start_datetime": "2025-04-21T04:38:47",
      "fingerprint_complete_datetime": "2025-04-21T04:38:47",
      "blockchain_provider": "ALGORAND",
      "blockchain_app_id": 738210995,
      "api_client_id": "qudefense-outlook-api",
      "tags": {
        "Department": "IT",
        "User": "John"
      },
      "fingerprint_verification_history": [
        {
          "created_at": "2025-04-21T04:38:56",
          "fingerprint_verify_result": "MATCH",
          "tags": {
            "Office": "Toronto",
            "User": "Henry"
          }
        }
      ]
    },
    {
      "file_id": "004b42f2-ecb1-4f53-9a9e-1527afab92ab",
      "file_name": "s3_upload_and_return_presigned_url.py",
      "file_path": "ozacgljb/utjfdqlb/s3_upload_and_return_presigned_url.py",
      "file_size": 10628,
      "storage_provider": "AWS-S3",
      "storage_bucket_name": "api-test-qudefense",
      "fingerprint_requested_datetime": "2025-04-21T04:38:31",
      "fingerprint_start_datetime": "2025-04-21T04:38:31",
      "fingerprint_complete_datetime": "2025-04-21T04:38:31",
      "blockchain_provider": "ALGORAND",
      "blockchain_app_id": 738210981,
      "api_client_id": "qudefense-outlook-api",
      "tags": {
        "Department": "IT",
        "User": "John"
      },
      "fingerprint_verification_history": [
        {
          "created_at": "2025-04-21T04:38:40",
          "fingerprint_verify_result": "MATCH",
          "tags": {
            "Office": "Toronto",
            "User": "Henry"
          }
        }
      ]
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

Generated: 2025-04-24 19:34:58 UTC