Developer API & SDKs
Relevant source files
The following files were used as context for generating this wiki page:
The TrueLens Developer API provides programmatic access to an AI-powered content verification platform designed to detect AI-generated text, fraudulent documents, and suspicious domains. By integrating these services, developers can automate authenticity checks and generate trust scores for web content and uploaded files within their own applications.
The platform architecture follows a RESTful pattern, utilizing a Next.js frontend that proxies requests to a high-performance FastAPI ML service. This infrastructure supports multi-signal analysis, including stylometry for text and cryptographic signing for document integrity.
Sources: truelens-app/src/app/developers/page.tsx:1-12, truelens-app/src/app/api/v1/scans/route.ts:3-5
API Architecture & Authentication
TrueLens operates as a multi-tier system where the frontend API routes act as a bridge to the backend machine learning services. Developers interact with the v1 API namespace using standard HTTP methods.
Authentication Flow
Access to the API requires a Bearer token provided in the Authorization header. API keys are managed via the developer dashboard and are linked to specific rate limits and scopes.
The sequence above illustrates how the Next.js layer sanitizes and proxies developer requests to the core analysis engine.
Sources: truelens-app/src/app/developers/page.tsx:64-75, truelens-app/src/app/api/v1/scans/route.ts:7-35, truelens-app/src/lib/types.ts:77-87
Core API Endpoints
The API is structured around three primary resource types: Scans (for text/URL analysis), Documents (for file integrity), and Verification (for checking existing signatures).
Resource Summary
| Method | Path | Description |
|---|---|---|
POST | /api/v1/scans | Submits content (URL or raw text) for AI analysis. |
GET | /api/v1/scans/:id | Retrieves detailed signal breakdown for a specific scan. |
POST | /api/v1/documents | Uploads a file for tamper detection and signing. |
POST | /api/v1/verify | Validates a document hash or Scan ID against the registry. |
GET | /api/v1/health | Service status and version information. |
Sources: truelens-app/src/app/developers/page.tsx:15-55
Analysis Request Schema
When submitting content to /api/v1/scans, the system expects a ScanRequest object. The contentType field determines whether the engine performs domain reputation checks or stylometry analysis.
// From truelens-app/src/lib/types.ts:89-93
export interface ScanRequest {
url?: string;
text?: string;
contentType: "url" | "text";
}
Data Models & Signals
The analysis results are encapsulated in a Scan object, which contains an ensemble of Signal objects. Each signal represents a specific detection vector.
Signal Types
The system evaluates content across multiple vectors to calculate a final trust score:
- text: Stylometry analysis (average sentence length, burstiness, vocabulary richness).
- domain: URL reputation (TLD analysis, HTTPS status, domain age).
- provenance: Historical matches and source verification.
- image: Forensics and GAN fingerprint detection.
The relationship between a Scan and its component Signals allows developers to inspect exactly why a piece of content was flagged.
Sources: truelens-app/src/lib/types.ts:13-39, truelens-app/src/lib/analysis.ts:251-275
Document Verification System
The API supports a cryptographic document signing workflow. When a document is uploaded via /api/v1/documents, the system generates a SHA-256 hash and, if verified, attaches a digital signature.
Verification Logic
Verification can be performed using either the id of the scan or the hash of the document.
Subscription Tiers & Rate Limits
The Developer API is metered based on subscription plans. Pricing influences the available signal types and daily request quotas.
| Tier | Scans / Month | API Rate Limit | Features |
|---|---|---|---|
| Free | 50 | Low | Text + URL Analysis |
| Pro | 5,000 | 1,000 / day | All signals + API SDKs |
| Enterprise | Unlimited | Custom | SLA + Custom Webhooks |
Sources: truelens-app/src/app/developers/page.tsx:168-215
Integration Examples
Node.js Integration
const response = await fetch('https://api.truelens.app/v1/scans', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
url: 'https://example.com/article',
contentType: 'url'
})
});
const { scan } = await response.json();
console.log(`Trust Score: ${scan.trustScore}`);
Sources: truelens-app/src/app/developers/page.tsx:77-91
Conclusion
The TrueLens Developer API & SDKs offer a robust gateway for integrating content authenticity checks into third-party platforms. By leveraging multi-signal ML analysis and cryptographic document verification, the API enables automated trust assessment for text, domains, and files.