Integrate with Elusiv using our REST API and smart contracts
Elusiv provides REST API endpoints for accessing the Knowledge Vault and managing research completions. All protected endpoints require wallet signature authentication and NFT ownership verification. Note: API endpoints use "library" in their paths for historical reasons, but they access the Knowledge Vault.
API base URL: https://api.elusiv.ai (production) or http://localhost:3001 (development)
All protected endpoints require wallet signature authentication:
Request a signing challenge from GET /api/auth/challenge
User signs the challenge with their wallet (ethers.js, web3.js, etc.)
Include signature in Authorization: Signature <signature> header
API verifies signature and checks ElusivAccessPass NFT ownership
Example signature string:
Access Elusiv Knowledge Vault (library_access).1703123456789.abc123def456
GET /healthHealth check endpoint providing system status.
{ "status": "healthy", "timestamp": "...", "version": "1.0.0" }GET /api/auth/challengeGet a signing challenge for authentication.
Parameters: action (optional, default: "library_access")
GET /api/libraryGet Knowledge Vault metadata and document list.
Requires: Wallet signature + ElusivAccessPass NFT
GET /api/library/categoriesGet available document categories.
GET /api/library/searchSearch documents by query.
Parameters: q (required), category (optional)
GET /api/library/download/:filenameDownload a PDF document.
Returns: PDF file stream
POST /api/research/complete/:requestIdSubmit a research completion by uploading a document.
Body: FormData with PDF file
GET /api/research/completion/:requestIdGet completion details for a research request.
POST /api/research/approve/:requestIdApprove a submitted completion (requester only).
POST /api/research/reject/:requestIdReject a submitted completion (requester only).
GET /api/research/pending-approvalsGet pending approvals for the authenticated user.
Elusiv uses three main smart contracts:
NFT contract for Access Pass membership. ABI available in frontend/src/lib/abis/ElusivAccessPass.json
Token contract for $ELUSIV. ABI available in frontend/src/lib/abis/ElusivToken.json
Research request queue contract. ABI available in frontend/src/lib/abis/ElusivResearchDesk.json
requestResearch(string query)Submit a research request to the Research Desk.
submitCompletion(uint256 requestId, string documentHash)Submit a completion for a research request.
approveCompletion(uint256 requestId)Approve a submitted completion.
// 1. Get challenge
const challengeResponse = await fetch('/api/auth/challenge');
const { data: challenge } = await challengeResponse.json();
// 2. Sign with wallet
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const signature = await signer.signMessage(challenge.challenge);
// 3. Access protected endpoints
const headers = {
'Authorization': `Signature ${signature}`
};
const libraryResponse = await fetch('/api/library', { headers });
const libraryData = await libraryResponse.json();Missing or invalid authentication signature.
User does not own an ElusivAccessPass NFT.
Too many requests. Retry after the specified time.
NFT verification service temporarily unavailable.
Signatures expire after 5 minutes for security.
Nonce-based one-time signatures prevent replay attacks.
Secure file access prevents directory traversal attacks.