H33.ai API Reference

Complete API documentation for integrating H33.ai's authentication, caching, and blockchain services.

Base URL

https://api.h33.ai/v1

Authentication

All API requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

Authentication

POST /auth/register

Register a new user with biometric capabilities

Request Body

{
  "email": "user@example.com",
  "displayName": "John Doe",
  "biometric": {
    "enabled": true,
    "methods": ["face", "fingerprint"]
  }
}

Response

{
  "user": {
    "id": "usr_2KtGQW1Z5y",
    "email": "user@example.com",
    "displayName": "John Doe",
    "createdAt": "2024-01-20T10:30:00Z"
  },
  "session": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2024-01-21T10:30:00Z"
  }
}
POST /auth/login

Authenticate user with multiple methods

Request Body

{
  "method": "biometric",
  "challenge": "challenge_token_from_create_challenge",
  "biometricData": {
    "type": "face",
    "credential": "base64_encoded_credential"
  }
}
GET /auth/challenge

Create authentication challenge for biometric login

Response

{
  "challenge": "chl_9Xk2mP3nQ8",
  "publicKey": {
    "challenge": "random_bytes_base64",
    "rp": {
      "name": "H33.ai",
      "id": "h33.ai"
    },
    "user": {
      "id": "user_id_bytes",
      "name": "user@example.com",
      "displayName": "John Doe"
    }
  },
  "expiresAt": "2024-01-20T10:35:00Z"
}

Cache Operations

GET /cache/{key}

Retrieve value from AI-optimized cache

Response

{
  "key": "user:123:profile",
  "value": {
    "name": "John Doe",
    "preferences": { "theme": "dark" }
  },
  "metadata": {
    "hitRate": 0.94,
    "latency": 0.4,
    "aiOptimized": true,
    "ttl": 3600
  }
}
POST /cache/{key}

Store value with AI-optimized TTL

Request Body

{
  "value": {
    "name": "John Doe",
    "preferences": { "theme": "dark" }
  },
  "ttl": 3600,
  "aiOptimize": true
}
GET /cache/analytics

Get real-time cache performance metrics

Response

{
  "metrics": {
    "hitRate": 0.941,
    "missRate": 0.059,
    "avgLatency": 0.4,
    "p95Latency": 0.8,
    "p99Latency": 1.2
  },
  "ai": {
    "patternsDetected": 14,
    "prefetchAccuracy": 0.91,
    "optimizationsSuggested": 7,
    "projectedSavings": 4200
  },
  "usage": {
    "operations": 1250000,
    "dataTransferred": "125GB",
    "uniqueKeys": 45000
  }
}

Blockchain

POST /blockchain/audit

Create immutable audit log entry

Request Body

{
  "action": "data_access",
  "userId": "usr_2KtGQW1Z5y",
  "resourceId": "doc_8Hk3mN9pQ2",
  "metadata": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "permissions": ["read", "download"]
  }
}

Response

{
  "auditId": "aud_7Xm2pQ8nK3",
  "blockchainTx": "0x742d35cc6634c0532925a3b844bc454e",
  "timestamp": "2024-01-20T10:30:00Z",
  "signature": "0x9f86d081884c7d659a2feaa0c55ad015a..."
}
GET /blockchain/audit/{auditId}/verify

Verify audit entry integrity

Response

{
  "verified": true,
  "audit": {
    "id": "aud_7Xm2pQ8nK3",
    "action": "data_access",
    "timestamp": "2024-01-20T10:30:00Z"
  },
  "blockchain": {
    "network": "solana",
    "txHash": "0x742d35cc6634c0532925a3b844bc454e",
    "blockHeight": 12345678,
    "confirmations": 35
  }
}

Biometric

POST /biometric/enroll

Enroll new biometric credential

Request Body

{
  "userId": "usr_2KtGQW1Z5y",
  "type": "face",
  "credential": {
    "publicKey": "base64_encoded_public_key",
    "attestation": "base64_encoded_attestation"
  },
  "device": {
    "id": "device_unique_id",
    "name": "iPhone 15 Pro",
    "platform": "iOS"
  }
}
POST /biometric/verify

Verify biometric authentication

Request Body

{
  "challenge": "chl_9Xk2mP3nQ8",
  "credential": {
    "id": "credential_id",
    "signature": "base64_encoded_signature",
    "clientData": "base64_encoded_client_data"
  }
}

Error Codes

Code Name Description
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid API key
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Rate Limited Too many requests
500 Internal Error Server error

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The email field is required",
    "details": {
      "field": "email",
      "reason": "missing"
    }
  },
  "requestId": "req_8Hk3mN9pQ2"
}

Rate Limits

API rate limits vary by plan:

Plan Requests/Second Requests/Day
Free 10 10,000
Professional 100 1,000,000
Enterprise 1,000+ Unlimited

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642680000

SDKs

JavaScript/TypeScript

npm install @h33/platform
View on GitHub →

Python

pip install h33-platform
View on GitHub →

Go

go get github.com/h33-ai/go-sdk
View on GitHub →

Java

<dependency>
  <groupId>ai.h33</groupId>
  <artifactId>h33-sdk</artifactId>
  <version>1.0.0</version>
</dependency>
View on GitHub →