Blockchain API¶

Programmatic access to blockchain anchoring and verification features.

Authentication¶

All endpoints require API authentication. See [Authentication(authentication.md) for details.

Authorization: Bearer <api_token>

Endpoints¶

Verify a Record¶

Verify that a content hash exists in the blockchain audit trail.

POST /api/v1/audit/verify

Request Body:

{
  "content_hash": "0x1234abcd..."
}

Field	Type	Required	Description
`content_hash`	string	Yes	SHA-256 hash (64 hex chars, with or without 0x)

Response (200 OK):

{
  "verified": true,
  "anchor": {
    "id": 123,
    "merkle_root": "0xdef456789...",
    "tx_hash": "0x789abcdef...",
    "block_number": 12345678,
    "confirmed_at": "2026-01-15T10:30:00Z",
    "network": "polygon_mainnet",
    "explorer_url": "https://polygonscan.com/tx/0x789abc..."
  },
  "proof": {
    "content_hash": "0x1234abcd...",
    "leaf_index": 42,
    "proof_path": ["0xaaa...", "0xbbb...", "0xccc..."]
  }
}

Response (404 Not Found):

{
  "verified": false,
  "error": "Content hash not found in audit trail"
}

List Anchors¶

Returns a paginated list of blockchain anchors for your organization.

GET /api/v1/audit/anchors

Query Parameters:

Parameter	Type	Default	Description
`status`	string	all	Filter: `confirmed`, `pending`, `failed`
`from_date`	date	-	Start date (YYYY-MM-DD)
`to_date`	date	-	End date (YYYY-MM-DD)
`page`	integer	1	Page number
`per_page`	integer	25	Results per page (max 100)

Response (200 OK):

{
  "anchors": [
    {
      "id": 123,
      "merkle_root": "0xdef456...",
      "leaf_count": 150,
      "status": "confirmed",
      "network": "polygon_mainnet",
      "tx_hash": "0x789abc...",
      "block_number": 12345678,
      "confirmed_at": "2026-01-15T10:30:00Z",
      "created_at": "2026-01-15T10:00:00Z",
      "explorer_url": "https://polygonscan.com/tx/0x789abc..."
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 123,
    "per_page": 25
  }
}

Get Anchor Details¶

Returns detailed information about a specific anchor, including all associated proofs.

GET /api/v1/audit/anchors/:id

Response (200 OK):

{
  "anchor": {
    "id": 123,
    "merkle_root": "0xdef456...",
    "leaf_count": 150,
    "status": "confirmed",
    "network": "polygon_mainnet",
    "tx_hash": "0x789abc...",
    "block_number": 12345678,
    "gas_used": 45000,
    "confirmed_at": "2026-01-15T10:30:00Z",
    "created_at": "2026-01-15T10:00:00Z",
    "first_record_at": "2026-01-15T09:00:00Z",
    "last_record_at": "2026-01-15T10:00:00Z",
    "explorer_url": "https://polygonscan.com/tx/0x789abc..."
  },
  "proofs": [
    {
      "content_hash": "0x111...",
      "auditable_type": "AuditLog",
      "auditable_id": 456,
      "leaf_index": 0,
      "proof_path": ["0xaaa...", "0xbbb..."]
    },
    {
      "content_hash": "0x222...",
      "auditable_type": "AuditLog",
      "auditable_id": 457,
      "leaf_index": 1,
      "proof_path": ["0xccc...", "0xddd..."]
    }
  ]
}

Batch Verify Proofs¶

Verify multiple content hashes in a single request.

POST /api/v1/audit/verify/batch

Request Body:

{
  "records": [
    { "content_hash": "0x111..." },
    { "content_hash": "0x222..." },
    { "content_hash": "0x333..." }
  ]
}

Response (200 OK):

{
  "results": [
    {
      "content_hash": "0x111...",
      "verified": true,
      "anchor_id": 123,
      "tx_hash": "0xabc..."
    },
    {
      "content_hash": "0x222...",
      "verified": true,
      "anchor_id": 123,
      "tx_hash": "0xabc..."
    },
    {
      "content_hash": "0x333...",
      "verified": false,
      "error": "Not found"
    }
  ],
  "summary": {
    "total": 3,
    "verified": 2,
    "failed": 1
  }
}

Generate Compliance Report¶

Generate a PDF compliance report with blockchain proofs.

GET /api/v1/audit/reports/audit_trail.pdf

Query Parameters:

Parameter	Type	Default	Description
`from`	datetime	30 days ago	Start datetime (ISO 8601)
`to`	datetime	now	End datetime (ISO 8601)
`include_proofs`	boolean	true	Include Merkle proofs

Response (200 OK):

Returns PDF binary data with Content-Type: application/pdf.

Generate EU AI Act Report¶

Generate a PDF report for EU AI Act compliance.

GET /api/v1/audit/reports/eu_ai_act.pdf

Query Parameters:

Parameter	Type	Default	Description
`from`	datetime	6 months ago	Start datetime
`to`	datetime	now	End datetime

Response (200 OK):

Returns PDF binary data with comprehensive EU AI Act compliance information.

Error Responses¶

All error responses follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

HTTP Code	Error Code	Description
400	INVALID_HASH	Content hash format is invalid
401	UNAUTHORIZED	Missing or invalid API token
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Server error

Rate Limits¶

Blockchain API endpoints have the following rate limits:

Endpoint	Limit
Verify single	60/minute
Batch verify	10/minute
List anchors	30/minute
Generate reports	5/minute

Webhooks¶

Subscribe to blockchain events via webhooks:

Event	Description
`audit.anchor.submitted`	Merkle root submitted to blockchain
`audit.anchor.confirmed`	Anchor confirmed on-chain
`audit.anchor.failed`	Anchor submission failed

See [Webhooks(webhooks.md) for configuration details.

SDK Examples¶

Ruby SDK¶

require 'kiket'

client = Kiket::Client.new(api_token: ENV['KIKET_API_TOKEN'])

# Verify a content hash
result = client.audit.verify(content_hash: "0x1234abcd...")
puts result[:verified] # => true

# List anchors
anchors = client.audit.anchors(status: 'confirmed', per_page: 50)
anchors.each { |a| puts "#{a[:id]}: #{a[:merkle_root]}" }

# Download compliance report
pdf = client.audit.export_report(
  type: :audit_trail,
  from: '2026-01-01',
  to: '2026-01-31'
)
File.binwrite('audit_report.pdf', pdf)

Python SDK¶

from kiket import Client

client = Client(api_token=os.environ['KIKET_API_TOKEN'])

# Verify a content hash
result = client.audit.verify(content_hash="0x1234abcd...")
print(result['verified'])  # True

# List anchors
anchors = client.audit.anchors(status='confirmed', per_page=50)
for anchor in anchors:
    print(f"{anchor['id']}: {anchor['merkle_root']}")

# Download compliance report
pdf = client.audit.export_report(
    type='audit_trail',
    from_date='2026-01-01',
    to_date='2026-01-31'
)
with open('audit_report.pdf', 'wb') as f:
    f.write(pdf)

Node.js SDK¶

const { Client } = require('@kiket/sdk');

const client = new Client({ apiToken: process.env.KIKET_API_TOKEN });

// Verify a content hash
const result = await client.audit.verify({ contentHash: '0x1234abcd...' });
console.log(result.verified); // true

// List anchors
const anchors = await client.audit.anchors({ status: 'confirmed', perPage: 50 });
anchors.forEach(a => console.log(`${a.id}: ${a.merkleRoot}`));

// Download compliance report
const pdf = await client.audit.exportReport({
  type: 'audit_trail',
  from: '2026-01-01',
  to: '2026-01-31'
});
fs.writeFileSync('audit_report.pdf', pdf);

CLI Examples¶

Listing Anchors¶

# List all recent anchors
kiket audit anchors

# Filter by status
kiket audit anchors --status confirmed

# Filter by network
kiket audit anchors --network polygon_mainnet

# Output as JSON
kiket audit anchors --format json

Getting Proofs¶

# Get proof for an audit record
kiket audit proof 12345

# Save proof to file
kiket audit proof 12345 --format file --output proof.json

# Get proof for AI audit log
kiket audit proof 789 --type AIAuditLog

Verifying Proofs¶

# Verify from file
kiket audit verify proof.json

# Verify from JSON string
kiket audit verify --json '{"content_hash":"0x...","proof":[],...}'

# Verify locally (Merkle proof only, no blockchain check)
kiket audit verify proof.json --local

Exporting Reports¶

# Export audit trail report
kiket audit export audit-trail --start 2026-01-01 --end-date 2026-01-31

# Export EU AI Act compliance report
kiket audit export eu-ai-act --start 2026-01-01 --end-date 2026-06-30

# Specify output file
kiket audit export audit-trail --start 2026-01-01 --end-date 2026-01-31 --output my_report.pdf

Checking Status¶

# Show blockchain audit status summary
kiket audit status

Blockchain Audit Trails - How anchoring and verification work
[Authentication(authentication.md) - API authentication

Blockchain API¶

Authentication¶

Endpoints¶

Verify a Record¶

List Anchors¶

Get Anchor Details¶

Batch Verify Proofs¶

Generate Compliance Report¶

Generate EU AI Act Report¶

Error Responses¶

Rate Limits¶

Webhooks¶

SDK Examples¶

Ruby SDK¶

Python SDK¶

Node.js SDK¶

CLI Examples¶

Listing Anchors¶

Getting Proofs¶

Verifying Proofs¶

Exporting Reports¶

Checking Status¶

Related¶