API Reference

Development: http://localhost:3004
Production: https://credit-api.earna.sh (planned)

Authorization: Bearer <token>

// Using NextAuth
const session = await getSession();
const token = session?.accessToken;
 
// Using API Key (service accounts)
const token = process.env.CREDIT_ENGINE_API_KEY;

GET /api/health

{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "ai": "ready",
    "cache": "connected"
  }
}

POST /api/chat
Content-Type: application/json

interface ChatRequest {
  messages: Message[];
  context?: {
    creditScore?: number;
    creditGoal?: number;
    timeframe?: string;
    financialSituation?: {
      income: number;
      debt: number;
      assets: number;
    };
  };
  options?: {
    streamResponse?: boolean;
    includeAnalysis?: boolean;
    language?: 'en' | 'fr';
  };
}
 
interface Message {
  role: 'user' | 'assistant' | 'system';
  content: string;
  metadata?: Record<string, any>;
}

{
  "response": {
    "content": "Based on your credit score of 650...",
    "recommendations": [
      {
        "action": "Pay down credit card balances",
        "impact": "+40 points",
        "priority": "high",
        "timeline": "3 months"
      }
    ],
    "analysis": {
      "currentSituation": "...",
      "opportunities": ["..."],
      "risks": ["..."]
    }
  },
  "usage": {
    "promptTokens": 1500,
    "completionTokens": 800,
    "totalCost": 0.023
  }
}

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ messages, options: { streamResponse: true } })
});
 
const reader = response.body.getReader();
const decoder = new TextDecoder();
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
 
  const chunk = decoder.decode(value);
  console.log('Received:', chunk);
}

POST /api/analyze/report
Content-Type: application/json

interface AnalyzeReportRequest {
  reportData: string; // Base64 encoded PDF or text
  bureau: 'experian' | 'equifax' | 'transunion';
  options?: {
    extractScore?: boolean;
    identifyIssues?: boolean;
    generateRecommendations?: boolean;
  };
}

{
  "analysis": {
    "score": 720,
    "scoreFactors": [
      {
        "factor": "Payment History",
        "impact": "positive",
        "weight": 35,
        "details": "100% on-time payments"
      }
    ],
    "accounts": [
      {
        "name": "Credit Card XYZ",
        "type": "revolving",
        "status": "open",
        "balance": 500,
        "limit": 5000,
        "utilization": 10
      }
    ],
    "issues": [
      {
        "severity": "medium",
        "description": "High utilization on Card ABC",
        "recommendation": "Pay down to below 30%"
      }
    ]
  }
}

POST /api/analyze/impact
Content-Type: application/json

interface ImpactRequest {
  currentScore: number;
  actions: Action[];
  timeframe: number; // months
}
 
interface Action {
  type: 'pay_down' | 'new_account' | 'close_account' | 'dispute';
  details: Record<string, any>;
}

{
  "predictions": [
    {
      "action": "Pay down credit cards to 30% utilization",
      "estimatedImpact": {
        "points": 40,
        "newScore": 690,
        "confidence": 85
      },
      "timeline": {
        "immediate": 10,
        "threeMonths": 25,
        "sixMonths": 40
      }
    }
  ],
  "totalImpact": {
    "bestCase": 755,
    "likelyCase": 720,
    "worstCase": 680
  }
}

POST /api/generate/dispute
Content-Type: application/json

interface DisputeRequest {
  bureau: 'experian' | 'equifax' | 'transunion';
  disputeType: 'error' | 'fraud' | 'outdated' | 'unverified';
  accountInfo: {
    creditor: string;
    accountNumber: string;
    disputeReason: string;
  };
  supportingEvidence?: string[];
  userInfo: {
    name: string;
    address: string;
    ssn?: string; // Last 4 digits only
  };
}

{
  "document": {
    "content": "Dear Experian...",
    "format": "text",
    "metadata": {
      "bureauAddress": "...",
      "mailingInstructions": "...",
      "trackingNumber": "DIS-2025-001234"
    }
  },
  "instructions": [
    "Print and sign the letter",
    "Include copies of supporting documents",
    "Send via certified mail",
    "Keep tracking information"
  ],
  "followUp": {
    "expectedResponse": "30-45 days",
    "nextSteps": ["..."]
  }
}

POST /api/generate/goodwill
Content-Type: application/json

interface GoodwillRequest {
  creditor: string;
  accountNumber: string;
  latePaymentDates: string[];
  explanation: string;
  customerHistory: {
    accountAge: number; // months
    previousLatePayments: number;
  };
}

POST /api/monitor/setup
Content-Type: application/json

interface MonitoringSetup {
  bureaus: ('experian' | 'equifax' | 'transunion')[];
  frequency: 'daily' | 'weekly' | 'monthly';
  alerts: {
    scoreChange: number; // Point threshold
    newAccount: boolean;
    hardInquiry: boolean;
    latePayment: boolean;
  };
  notifications: {
    email?: string;
    sms?: string;
    webhook?: string;
  };
}

GET /api/monitor/status

{
  "monitoring": {
    "active": true,
    "since": "2025-01-01T00:00:00Z",
    "lastCheck": "2025-01-15T10:00:00Z",
    "nextCheck": "2025-01-16T10:00:00Z"
  },
  "recentAlerts": [
    {
      "type": "score_increase",
      "date": "2025-01-10T15:30:00Z",
      "details": {
        "previousScore": 680,
        "newScore": 695,
        "change": 15
      }
    }
  ],
  "configuration": {
    "bureaus": ["experian", "equifax"],
    "frequency": "daily",
    "alerts": {
      "scoreChange": 5,
      "newAccount": true
    }
  }
}

interface WebhookEvent {
  id: string;
  type: EventType;
  timestamp: string;
  data: Record<string, any>;
}
 
type EventType =
  | 'score.changed'
  | 'alert.created'
  | 'goal.achieved'
  | 'report.available'
  | 'dispute.updated'
  | 'monitoring.error';

{
  "id": "evt_2025_abc123",
  "type": "score.changed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "userId": "user_123",
    "previousScore": 680,
    "newScore": 695,
    "change": 15,
    "bureau": "experian",
    "factors": [
      "Credit utilization decreased",
      "Payment history improved"
    ]
  }
}

import crypto from 'crypto';
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is invalid",
    "details": {
      "field": "creditScore",
      "issue": "Must be between 300 and 900"
    }
  },
  "requestId": "req_abc123",
  "timestamp": "2025-01-15T10:30:00Z"
}

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642255200

import { CreditEngineClient } from '@earna/credit-engine-sdk';
 
const client = new CreditEngineClient({
  apiKey: process.env.CREDIT_ENGINE_API_KEY,
  baseUrl: 'https://credit-api.earna.sh'
});
 
// Chat with AI coach
const response = await client.chat({
  messages: [
    { role: 'user', content: 'How can I improve my credit score?' }
  ],
  context: {
    creditScore: 650,
    creditGoal: 750
  }
});
 
// Analyze credit impact
const impact = await client.analyzeImpact({
  currentScore: 650,
  actions: [
    { type: 'pay_down', details: { amount: 5000 } }
  ],
  timeframe: 6
});

from earna_credit import CreditEngineClient
 
client = CreditEngineClient(
    api_key="your_api_key",
    base_url="https://credit-api.earna.sh"
)
 
# Chat with AI coach
response = client.chat(
    messages=[
        {"role": "user", "content": "How can I improve my credit score?"}
    ],
    context={
        "credit_score": 650,
        "credit_goal": 750
    }
)
 
# Generate dispute letter
letter = client.generate_dispute(
    bureau="experian",
    dispute_type="error",
    account_info={
        "creditor": "ABC Bank",
        "account_number": "****1234",
        "dispute_reason": "Account not mine"
    }
)