API Specification - Data Proof Labs

Base URL

Production: https://api.dataprooflabs.com
Testnet: https://testnet-api.dataprooflabs.com
Development: http://localhost:3411/api

Authentication

Data Proof Labs API uses API Key authentication. Include your API key in the request header:

X-API-Key: your-api-key-here

You can obtain an API key by registering at the Data Proof Labs portal.

Proof Management

POST /proof API Key Required

Create Single Proof

Creates a proof record on the blockchain for a single data item.

Request Parameters

Parameter	Type	Required	Description
recordId	string	Required	Unique identifier for the record
entityId	string	Optional	Entity/category identifier
data	string	Required	Base64 encoded data to prove
blockchainType	string	Optional	Ethereum or Bitcoin (default: Ethereum)
networkType	string	Optional	Sepolia, TestNet, etc.
metadata	object	Optional	Additional metadata

Example Request

{
  "recordId": "doc-2025-001",
  "entityId": "legal-documents", 
  "data": "VGhpcyBpcyBhIHNhbXBsZSBkb2N1bWVudA==",
  "blockchainType": "Ethereum",
  "networkType": "Sepolia",
  "metadata": {
    "department": "legal",
    "category": "contract"
  }
}

Example Response

{
  "success": true,
  "hash": "0xa1b2c3d4e5f6789...",
  "blockchainType": "Ethereum",
  "blockchainTransactionId": "0x1234567890abcdef...",
  "blockNumber": 12345678,
  "timestamp": "2025-08-24T13:30:00Z",
  "recordId": "doc-2025-001",
  "entityId": "legal-documents",
  "orgId": "your-org-id",
  "confirmationStatus": 1,
  "message": "Proof recorded successfully"
}

GET /proof/{recordId}/verify API Key Required

Verify Proof

Verifies a proof record by checking its existence on the blockchain.

Path Parameters

Parameter	Type	Description
recordId	string	The record ID to verify

Example Response

{
  "isValid": true,
  "recordId": "doc-2025-001",
  "transactionHash": "0x1234567890abcdef...",
  "blockNumber": 12345678,
  "confirmations": 15,
  "networkType": "Sepolia",
  "timestamp": "2025-08-24T13:30:00Z"
}

GET /proof/history API Key Required

Get Proof History

Retrieves proof history for the current tenant/organization.

Example Response

[
  {
    "recordId": "doc-2025-001",
    "entityId": "legal-documents",
    "orgId": "your-org-id",
    "data": "Document content hash",
    "hash": "0xa1b2c3d4e5f6789...",
    "blockchainType": "Ethereum",
    "networkType": "Sepolia",
    "transactionHash": "0x1234567890abcdef...",
    "blockNumber": 12345678,
    "timestamp": "2025-08-24T13:30:00Z",
    "isVerified": true
  }
]

Batch Processing

POST /proof/batch API Key Required

Create Batch Proof

Creates multiple proof records in a single blockchain transaction using Merkle tree optimization.

Request Parameters

Parameter	Type	Required	Description
batchId	string	Optional	Custom batch identifier
dataItems	array	Required	Array of data items to prove
blockchainType	string	Optional	Ethereum or Bitcoin
includeIndividualProofs	boolean	Optional	Include individual proof records

Example Request

{
  "batchId": "batch-2025-08-24-001",
  "dataItems": [
    {
      "recordId": "item-001",
      "entityId": "documents",
      "data": "VGVzdCBkYXRhIDE="
    },
    {
      "recordId": "item-002", 
      "entityId": "documents",
      "data": "VGVzdCBkYXRhIDI="
    }
  ],
  "blockchainType": "Ethereum",
  "includeIndividualProofs": true
}

Example Response

{
  "success": true,
  "batchId": "batch-2025-08-24-001",
  "merkleRoot": "0xabcdef1234567890...",
  "transactionHash": "0x9876543210fedcba...",
  "blockchainType": "Ethereum",
  "networkType": "Sepolia",
  "totalItems": 2,
  "timestamp": "2025-08-24T13:35:00Z",
  "individualProofs": [
    {
      "recordId": "item-001",
      "entityId": "documents",
      "hash": "0x1111222233334444..."
    }
  ]
}

GET /proof/batch/{batchId}/merkle/{recordId} API Key Required

Get Merkle Proof

Retrieves the Merkle proof for a specific record within a batch.

Example Response

{
  "recordId": "item-001",
  "batchId": "batch-2025-08-24-001",
  "leafHash": "0x1111222233334444...",
  "merkleRoot": "0xabcdef1234567890...",
  "proofPath": [
    "0x2222333344445555...",
    "0x3333444455556666..."
  ],
  "leafIndex": 0,
  "totalLeaves": 2
}

Account Management

GET /proof/balance API Key Required

Get Balance Status

Returns current blockchain wallet balances and transaction cost estimates.

Example Response

{
  "balances": [
    {
      "blockchainType": "Ethereum",
      "networkName": "Sepolia",
      "balance": "0.025",
      "balanceFormatted": "0.025 ETH",
      "usdValue": 65.50,
      "isActive": true,
      "address": "0x742d35cc..."
    }
  ],
  "totalValueUsd": 110.50,
  "lastUpdated": "2025-08-24T13:40:00Z"
}

Error Handling

The API uses conventional HTTP response codes and returns error details in JSON format:

Status Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid API key
404	Not Found	Resource not found
429	Rate Limited	Too many requests
500	Server Error	Internal server error

Error Response Format

{
  "success": false,
  "error": "Invalid API key",
  "errorCode": "AUTH_001",
  "message": "The provided API key is invalid or expired",
  "timestamp": "2025-08-24T13:45:00Z"
}