Overview

The Verdex API provides programmatic access to project assessment, DFI matching, clause search, AI-powered chat assistance, and transition loan draft generation. All endpoints accept JSON requests and return JSON responses.

POST /api/assess

Submit a project for LMA transition eligibility assessment. Returns comprehensive scoring across five LMA components, greenwashing risk analysis, DFI matches, and AI-generated KPI/SPT recommendations.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/assess \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "Kano Solar Farm Phase II",
    "country": "nigeria",
    "sector": "energy",
    "projectType": "Solar PV",
    "description": "200MW solar PV installation with battery storage",
    "totalCost": 50000000,
    "debtAmount": 40000000,
    "equityAmount": 10000000,
    "currentEmissions": { "scope1": 5000, "scope2": 2000, "scope3": 15000 },
    "targetEmissions": { "scope1": 500, "scope2": 0, "scope3": 8000 },
    "targetYear": 2030,
    "transitionStrategy": "Phase out diesel generators, install solar PV",

Request Body

typescriptRequest

{
  // Required fields
  "projectName": "Kano Solar Farm Phase II",
  "country": "nigeria",  // Must be African country
  "sector": "energy",    // energy | agriculture | transport | manufacturing | mining | real_estate | water

  // Optional fields
  "projectType": "Solar PV",
  "description": "200MW solar PV installation with battery storage...",
  "totalCost": 50000000,
  "debtAmount": 40000000,
  "equityAmount": 10000000,
  "currentEmissions": {
    "scope1": 5000,
    "scope2": 2000,

Response

typescriptResponse

{
  "projectName": "Kano Solar Farm Phase II",
  "country": "nigeria",
  "countryName": "Nigeria",
  "sector": "energy",
  "targetYear": 2030,

  // Eligibility
  "eligibilityStatus": "eligible" | "partial" | "ineligible",
  "ineligibilityReasons": [],  // Reasons if ineligible

  // Scoring
  "overallScore": 75,           // 0-100, after greenwashing penalty
  "lmaBaseScore": 80,           // Raw LMA score before penalty
  "greenwashingPenalty": 5,     // Points deducted

💡Scoring Logic

Projects score 0-100 across five LMA components (20 points each). Greenwashing red flags reduce the LMA score: high severity (-25 pts), medium (-15 pts), low (-5 pts). DNSH is an independent score (0-100) displayed separately. Fossil fuel projects and non-African locations are automatically ineligible. Eligibility thresholds: ≥60 eligible, 30-59 partial, <30 ineligible.

POST /api/location-risk

Get climate intelligence and location-specific risk assessment for a project site. Returns historical climate data, CMIP6 projections, risk metrics, and site intelligence.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/location-risk \
  -H "Content-Type: application/json" \
  -d '{
    "country": "kenya",
    "sector": "energy",
    "city": "Nairobi"
  }'

Request Body

typescriptRequest

{
  "country": "kenya",     // Required: African country code
  "sector": "energy",     // Required: Project sector
  "city": "Nairobi"       // Optional: Defaults to capital city
}

Response

typescriptResponse

{
  "coordinates": {
    "latitude": -1.2921,
    "longitude": 36.8219,
    "locationName": "Nairobi, Kenya"
  },
  "overallRiskScore": 45,  // 0-100, lower = less risk

  "historicalData": {
    "averageTemperature": 19.2,      // °C, 10-year average
    "annualPrecipitation": 958,       // mm/year
    "extremeHeatDays": 12,            // Days >35°C per year
    "drySeasonMonths": [1, 2, 7, 8, 9],
    "droughtRisk": "medium",
    "floodRisk": "medium"

💡Climate Data Source

Location risk uses Open-Meteo APIs (free, no API key required) for historical weather archive (10-year data) and CMIP6 climate projections (SSP2-4.5, SSP5-8.5 scenarios for 2030/2050).

POST /api/location-insight

Generate AI-powered climate insights tailored to a specific project. Provides contextualized recommendations, key risks, and opportunities based on climate data and project details.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/location-insight \
  -H "Content-Type: application/json" \
  -d '{
    "sector": "energy",
    "country": "kenya",
    "locationName": "Nairobi",
    "historicalData": {
      "averageTemperature": 19.2,
      "annualPrecipitation": 958,
      "extremeHeatDays": 12,
      "droughtRisk": "medium",
      "floodRisk": "medium"
    },
    "siteIntelligence": {
      "waterAvailability": "moderate",

Response

typescriptResponse

{
  "success": true,
  "insights": {
    "projectContext": "This solar project benefits from Kenya's equatorial location with consistent 5.4 kWh/m²/day irradiance.",

    "recommendations": [
      {
        "text": "Install automated panel cleaning for dust management",
        "priority": "high"
      },
      {
        "text": "Consider battery storage for grid stability",
        "priority": "medium"
      }
    ],

💡Lazy Loading

AI insights are generated on-demand when users open the Climate Profile modal, not during initial assessment. This reduces API costs and latency for the main assessment flow.

POST /api/search

Search the LMA clause library using semantic search powered by embeddings.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "margin ratchet sustainability linked",
    "limit": 10,
    "filters": {
      "clauseType": "margin_ratchet"
    }
  }'

Request Body

typescriptRequest

{
  "query": "margin ratchet sustainability linked",
  "limit": 10,               // Default: 10
  "searchMode": "keyword",   // "keyword" | "clauseId"
  "filters": {
    "clauseType": "margin_ratchet",    // Optional
    "documentType": "facility_agreement",  // Optional
    "source": "LMA Sustainability-Linked Loan Principles"  // Optional
  }
}

Response

typescriptResponse

{
  "results": [
    {
      "id": "margin-ratchet-1",
      "score": 0.92,
      "content": "MARGIN RATCHET CLAUSE (Sustainability-Linked)\n\nThe applicable Margin shall be adjusted...",
      "metadata": {
        "clauseType": "margin_ratchet",
        "documentType": "sustainability_linked_loan",
        "source": "LMA Sustainability-Linked Loan Principles"
      }
    }
  ],
  "totalFound": 7,
  "query": "margin ratchet sustainability linked",

GET /api/search

Retrieve search index metadata and available filter options.

cURL Example

bashcURL

curl -X GET https://www.verdx.site/api/search

Response

typescriptResponse

{
  "indexStats": {
    "totalVectors": 1250,
    "dimension": 384
  },
  "filters": {
    "clauseTypes": ["interest", "facility_terms", ...],
    "documentTypes": ["facility_agreement", "guide", ...]
  }
}

POST /api/upload-pdf

Upload a PDF document to extract project information using AI. Returns structured data including project details, emissions data, and financial information.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/upload-pdf \
  -F "pdf=@/path/to/your/project-document.pdf"

Request

typescriptRequest

// Content-Type: multipart/form-data
// Field: "pdf" - The PDF file to upload

const formData = new FormData();
formData.append('pdf', file);

const response = await fetch('/api/upload-pdf', {
  method: 'POST',
  body: formData
});

Response

typescriptResponse

{
  "success": true,
  "extractedText": "First 2000 characters of extracted text...",
  "rawDocumentText": "Full extracted text for greenwashing analysis",
  "textLength": 15420,
  "extractedFields": {
    "projectName": "Kano Solar Farm Phase II",
    "country": "Nigeria",
    "sector": "Energy",
    "projectType": "Solar PV",
    "description": "200MW solar PV installation with grid connection...",
    "climateTargets": "61% emissions reduction by 2030",
    "financingNeeded": 50000000,
    "debtAmount": 40000000,
    "equityAmount": 10000000,

💡PDF Processing

The endpoint uses pdf-parse for text extraction and AI for structured data extraction. Scanned or image-based PDFs will return an error. Maximum recommended file size is 10MB.

POST /api/chat

RAG-powered conversational assistant for LMA clause questions. Uses semantic search to retrieve relevant clauses and provides contextual answers with source citations.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How should I structure KPIs for a sustainability-linked loan?",
    "history": []
  }'

Request Body

typescriptRequest

{
  "message": "How should I structure KPIs for a sustainability-linked loan?",
  "history": [   // Optional: conversation history
    { "role": "user", "content": "What is a margin ratchet?" },
    { "role": "assistant", "content": "A margin ratchet is a mechanism..." }
  ]
}

Response

typescriptResponse

{
  "response": "For sustainability-linked loans, KPIs should be material to your business, measurable, externally verifiable, and benchmarkable against industry standards. Common KPIs include:\n\n1. **GHG Emissions** - Scope 1, 2, and ideally Scope 3\n2. **Renewable Energy Share** - % of total energy consumption\n3. **Energy Intensity** - Energy per unit of production\n\nBased on LMA guidelines...",

  "sources": [
    {
      "id": "kpi-definition-1",
      "clauseType": "kpi",
      "preview": "KEY PERFORMANCE INDICATOR DEFINITIONS\n\n\"KPI 1\" means the Borrower's absolute...",
      "score": 0.89
    },
    {
      "id": "reporting-covenant-1",
      "clauseType": "reporting",
      "preview": "SUSTAINABILITY REPORTING COVENANT\n\nThe Borrower shall...",
      "score": 0.82

💡RAG Pipeline

The chat endpoint generates embeddings for your question, searches the Pinecone vector store for relevant LMA clauses (top 5), then provides these as context to the AI model for generating grounded responses.

POST /api/clause-advice

Get AI-generated advice for applying a specific LMA clause template to your project. Returns relevance scoring, application guidance, and a contextualized clause example.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/clause-advice \
  -H "Content-Type: application/json" \
  -d '{
    "clause": {
      "content": "MARGIN RATCHET CLAUSE (Sustainability-Linked)...",
      "clauseType": "margin_ratchet",
      "source": "LMA Sustainability-Linked Loan Principles"
    },
    "projectContext": {
      "projectName": "Kano Solar Farm Phase II",
      "sector": "energy",
      "country": "Nigeria",
      "eligibilityStatus": "eligible",
      "kpis": [{ "name": "GHG Emissions Reduction", "description": "Annual tCO2e reduction" }],
      "spts": [{ "name": "Emissions Target", "target": "61% reduction by 2030" }]

Request Body

typescriptRequest

{
  "clause": {
    "content": "MARGIN RATCHET CLAUSE (Sustainability-Linked)\n\nThe applicable Margin shall be adjusted...",
    "clauseType": "margin_ratchet",
    "source": "LMA Sustainability-Linked Loan Principles"
  },
  "projectContext": {
    "projectName": "Kano Solar Farm Phase II",
    "sector": "energy",
    "country": "Nigeria",
    "eligibilityStatus": "eligible",
    "kpis": [
      { "name": "Installed Solar Capacity", "description": "Total MW installed" },
      { "name": "GHG Emissions Reduction", "description": "Annual tCO2e reduction" }
    ],

Response

typescriptResponse

{
  "success": true,
  "advice": {
    "relevanceScore": 9,  // 1-10 scale
    "relevanceSummary": "This margin ratchet clause is highly relevant for your solar project as it directly links financing costs to your GHG emissions reduction targets.",

    "howToApply": "Insert specific SPT thresholds: -10 bps for achieving 61% emissions reduction, +5 bps if target missed. Include annual verification requirement with DNV or similar provider.",

    "whenToUse": "Include in all sustainability-linked facility agreements where margin adjustments are tied to ESG performance.",

    "keyConsiderations": [
      "Ensure SPT thresholds are ambitious but achievable",
      "Align verification timing with annual reporting cycle",
      "Consider step-down mechanics for exceeding targets"
    ],

POST /api/clause-insight

Generate key points and ready-to-use adapted clause language for a specific LMA clause. Results are cached client-side in localStorage for instant retrieval on subsequent views.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/clause-insight \
  -H "Content-Type: application/json" \
  -d '{
    "clauseId": "margin-ratchet-1",
    "content": "MARGIN RATCHET CLAUSE (Sustainability-Linked)\n\nThe applicable Margin shall be adjusted quarterly based on the Borrower achievement of Sustainability Performance Targets...",
    "clauseType": "margin_ratchet",
    "documentType": "sustainability_linked_loan"
  }'

Request Body

typescriptRequest

{
  // Required fields
  "clauseId": "margin-ratchet-1",   // Unique clause identifier
  "content": "MARGIN RATCHET CLAUSE (Sustainability-Linked)...",  // Full clause text

  // Optional fields (improve response quality)
  "clauseType": "margin_ratchet",    // Type classification
  "documentType": "sustainability_linked_loan"  // Source document type
}

Response

typescriptResponse

{
  "clauseId": "margin-ratchet-1",
  "insight": {
    "summary": "• Links interest rate to sustainability performance\n• Rate drops when targets met, rises when missed\n• Creates financial incentive for environmental outcomes",

    "example": "The [Borrower] shall achieve a minimum [Target %] reduction in Scope 1 and 2 GHG emissions from the [Baseline] by [Target Year]. Upon verified achievement, the Margin shall decrease by [X] basis points; upon failure to achieve, the Margin shall increase by [Y] basis points."
  },
  "duration": 1234  // Generation time in milliseconds
}

💡Client-Side Caching

The search page automatically caches clause insights in localStorage. When a user views the same clause again, the cached summary and example display instantly without an API call. The cache key format is verdex_clause_insight_{clauseId} with version tracking for cache invalidation. Users can regenerate insights to refresh the cache.

💡AI Provider

This endpoint uses ASI1-mini for cost-efficient generation. Responses are optimized for clarity and practical application, explaining LMA concepts in plain language suitable for project developers without legal expertise.

POST /api/generate-draft

Generate a complete LMA transition loan project draft document. Uses a 3-phase AI pipeline (Analyze → Generate → Review) with RAG context from the LMA Guide to Transition Loans.

cURL Example

bashcURL

curl -X POST https://www.verdx.site/api/generate-draft \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "Kano Solar Farm Phase II",
    "country": "nigeria",
    "countryName": "Nigeria",
    "sector": "energy",
    "eligibilityStatus": "eligible",
    "overallScore": 75,
    "targetYear": 2030,
    "description": "200MW solar PV installation",
    "projectType": "Solar PV",
    "totalCost": 50000000,
    "debtAmount": 40000000,
    "equityAmount": 10000000,

Request Body

typescriptRequest

{
  // Required - from /api/assess response
  "projectName": "Kano Solar Farm Phase II",
  "country": "nigeria",
  "countryName": "Nigeria",
  "sector": "energy",
  "eligibilityStatus": "eligible",
  "overallScore": 75,
  "lmaComponents": [...],  // From assess response
  "greenwashingRisk": {...},  // From assess response
  "dfiMatches": [...],  // From assess response
  "nextSteps": [...],  // From assess response

  // Optional - enhances draft quality
  "targetYear": 2030,

Response

typescriptResponse

{
  "success": true,
  "draft": "# Kano Solar Farm Phase II\n## LMA Transition Loan Project Draft\n\n**Generated:** 2024-01-15\n**Country:** Nigeria\n**Sector:** Energy\n**Target DFI:** IFC\n\n---\n\n## 1. EXECUTIVE SUMMARY\n\n| Metric | Value |\n|--------|-------|\n| Project | Kano Solar Farm Phase II |\n| Total Investment | USD 50,000,000 |\n| Emissions Reduction | 61% by 2030 |\n...\n\n## 2. PROJECT DESCRIPTION\n\n[200+ word description with SBTi, Paris Agreement, NDC alignment]\n\n## 3. TRANSITION STRATEGY\n\n[Emissions tables for Scope 1/2/3, roadmap]\n\n## 4. FINANCING STRUCTURE\n\n[Debt/equity breakdown, DFI strategy]\n\n## 5. USE OF PROCEEDS & ELIGIBILITY\n\n[Categories, allocations, eligibility criteria]\n\n## 6. TRANSITION PLAN\n\n[Decarbonization pathway, governance framework, just transition]\n\n## 7. KPI FRAMEWORK\n\n[Detailed KPI table with baselines, targets, methodology]\n\n## 8. TPT MECHANISM\n\n[Transition Performance Targets with margin adjustments]\n\n## 9. RISK MITIGATION & EXTERNAL REVIEW\n\n[Red flag responses, verification schedule]\n\n## 10. DFI ROADMAP & ANNEXES\n\n[Submission timeline, documentation checklist, glossary]\n\n---\n\n## ANNEX A: ADAPTED LMA CLAUSES\n\n### Margin & Interest\n\n**1. Margin Ratchet**\n*Source: LMA Sustainability-Linked Loan Principles*\n\nKano Solar Farm Phase II (the \"Borrower\") shall be subject to margin adjustments...\n\n> **Application Note:** Insert specific SPT thresholds...\n\n---\n\n*End of Adapted Clauses Annex*",

  "metadata": {
    "generatedAt": "2024-01-15T10:30:00.000Z",
    "targetDFI": "IFC",
    "projectName": "Kano Solar Farm Phase II",
    "sector": "energy",
    "country": "Nigeria",
    "generationTime": 15420,  // milliseconds
    "phases": {
      "analyze": "complete",
      "generate": "complete",
      "review": "complete"

💡3-Phase Generation Pipeline

Phase 1 (Analyze): Extracts required keywords, identifies items to fix, and plans greenwashing mitigations
Phase 2 (Generate): Creates sections 1-5 and 6-10 in parallel for faster generation
Phase 3 (Review): Removes greenwashing language, validates dates (must be current year+), ensures required keywords present

⚠️Draft Generation Time

Draft generation typically takes 10-20 seconds due to the multi-phase AI pipeline. The endpoint has a 30-second timeout. For production use, consider implementing webhook callbacks or polling for long-running requests.

API Reference

Overview

POST /api/assess

cURL Example

Request Body

Response

POST /api/location-risk

cURL Example

Request Body

Response

POST /api/location-insight

cURL Example

Response

POST /api/search

cURL Example

Request Body

Response

GET /api/search

cURL Example

Response

POST /api/upload-pdf

cURL Example

Request

Response

POST /api/chat

cURL Example

Request Body

Response

POST /api/clause-advice

cURL Example

Request Body

Response

POST /api/clause-insight

cURL Example

Request Body

Response

POST /api/generate-draft

cURL Example

Request Body

Response