14 apis reference

Overview

This document provides a comprehensive reference for the platform's REST API endpoints. All endpoints return JSON and use standard HTTP status codes.

Base URL

Production: https://api.msvprotocol.com/v1
Staging: https://api-staging.msvprotocol.com/v1

Authentication

Most endpoints require authentication via JWT token:

Authorization: Bearer <token>

Wallet signature verification is used for on-chain actions.

---

Projects API

Create Project

POST /projects

Auth: Required (Issuer role)

Request Body:

{
  "name": "Solar Rajasthan 2024",
  "type": "Renewable Energy",
  "geography": "Rajasthan, India",
  "methodology": "VCS",
  "vintageYear": 2024,
  "verifierName": "Verra",
  "verifierRefId": "VCS-12345"
}

Response: 201 Created

{
  "id": "PJT-101",
  "name": "Solar Rajasthan 2024",
  "status": "Draft",
  "createdAt": "2026-01-14T10:00:00Z"
}

---

List Projects

GET /projects

Query Parameters:

• type - Filter by project type

• geography - Filter by geography

• vintageYear - Filter by vintage year

• status - Filter by status

• page - Page number (default: 1)

• limit - Items per page (default: 20)

Response: 200 OK

{
  "projects": [
    {
      "id": "PJT-101",
      "name": "Solar Rajasthan 2024",
      "type": "Renewable Energy",
      "geography": "Rajasthan, India",
      "vintageYear": 2024,
      "status": "Approved",
      "pricePerTon": 25.50,
      "unitsAvailable": 5000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

---

Get Project Details

GET /projects/:id

Response: 200 OK

{
  "id": "PJT-101",
  "name": "Solar Rajasthan 2024",
  "type": "Renewable Energy",
  "geography": "Rajasthan, India",
  "methodology": "VCS",
  "vintageYear": 2024,
  "verifierName": "Verra",
  "verifierRefId": "VCS-12345",
  "status": "Approved",
  "poai": {
    "status": "Approved",
    "assetIntegrity": "Verified",
    "dataIntegrity": "Verified",
    "processIntegrity": "Verified"
  },
  "pricing": {
    "pricePerTon": 25.50,
    "currency": "USD"
  },
  "issuance": {
    "cap": 10000,
    "issued": 5000,
    "retired": 250,
    "available": 4750
  },
  "onChain": {
    "projectTokenId": 101,
    "projectRecordAddress": "0x..."
  }
}

---

Upload Project Document

POST /projects/:id/documents

Auth: Required (Issuer role, project owner)

Request: Multipart form data

• file - Document file

• docType - Document type (KYC, OWNERSHIP, VERIFIER_REPORT, etc.)

Response: 201 Created

{
  "id": "DOC-123",
  "projectId": "PJT-101",
  "docType": "VERIFIER_REPORT",
  "uri": "https://storage.../doc.pdf",
  "hash": "0xabc123...",
  "uploadedAt": "2026-01-14T10:00:00Z"
}

---

Submit for PoAI

POST /projects/:id/poai/submit

Auth: Required (Issuer role, project owner)

Response: 200 OK

{
  "projectId": "PJT-101",
  "poaiCaseId": "POAI-456",
  "status": "SUBMITTED",
  "submittedAt": "2026-01-14T10:00:00Z"
}

---

Get PoAI Status

GET /projects/:id/poai/status

Response: 200 OK

{
  "projectId": "PJT-101",
  "poaiCaseId": "POAI-456",
  "status": "APPROVED",
  "checks": {
    "assetIntegrity": {
      "total": 3,
      "passed": 3,
      "failed": 0
    },
    "dataIntegrity": {
      "total": 2,
      "passed": 2,
      "failed": 0
    },
    "processIntegrity": {
      "total": 1,
      "passed": 1,
      "failed": 0
    }
  },
  "proofHashes": {
    "bundleHash": "0x...",
    "assetHash": "0x...",
    "dataHash": "0x...",
    "processHash": "0x..."
  }
}

---

PoAI API

List PoAI Cases

GET /poai/cases

Auth: Required (Reviewer role)

Query Parameters:

• state - Filter by state (SUBMITTED, IN_REVIEW, APPROVED, etc.)

• assignedTo - Filter by assigned reviewer

• page - Page number

• limit - Items per page

Response: 200 OK

{
  "cases": [
    {
      "id": "POAI-456",
      "projectId": "PJT-101",
      "state": "IN_REVIEW",
      "assignedReviewer": "REV-01",
      "submittedAt": "2026-01-14T10:00:00Z"
    }
  ],
  "pagination": {...}
}

---

Get PoAI Case Details

GET /poai/cases/:id

Auth: Required (Reviewer role)

Response: 200 OK

{
  "id": "POAI-456",
  "projectId": "PJT-101",
  "state": "IN_REVIEW",
  "assignedReviewer": "REV-01",
  "checks": [
    {
      "id": "CHECK-1",
      "category": "ASSET",
      "name": "Project Ownership Verified",
      "status": "PASS",
      "notes": "Ownership documents verified",
      "evidenceUri": "https://..."
    }
  ],
  "documents": [...],
  "submittedAt": "2026-01-14T10:00:00Z"
}

---

Add/Update PoAI Check

POST /poai/cases/:id/checks

Auth: Required (Reviewer role)

Request Body:

{
  "category": "ASSET",
  "name": "Project Ownership Verified",
  "status": "PASS",
  "notes": "Ownership documents verified",
  "evidenceUri": "https://..."
}

Response: 201 Created

{
  "id": "CHECK-1",
  "category": "ASSET",
  "status": "PASS",
  "createdAt": "2026-01-14T10:00:00Z"
}

---

Approve PoAI Case

POST /poai/cases/:id/approve

Auth: Required (Reviewer role)

Response: 200 OK

{
  "caseId": "POAI-456",
  "status": "APPROVED",
  "proofHashes": {
    "bundleHash": "0x...",
    "assetHash": "0x...",
    "dataHash": "0x...",
    "processHash": "0x..."
  },
  "approvedAt": "2026-01-14T10:00:00Z"
}

---

Retail API

Get Holdings

GET /me/holdings

Auth: Required (Retail user)

Response: 200 OK

{
  "totalCredits": 1.25,
  "totalValue": 31.88,
  "holdings": [
    {
      "projectId": "PJT-101",
      "projectName": "Solar Rajasthan 2024",
      "quantity": 0.25,
      "purchaseDate": "2026-01-10T10:00:00Z",
      "purchasePrice": 25.50
    },
    {
      "projectId": "PJT-102",
      "projectName": "Reforestation Amazon 2023",
      "quantity": 1.0,
      "purchaseDate": "2026-01-12T10:00:00Z",
      "purchasePrice": 30.00
    }
  ]
}

---

Purchase Credits

POST /purchase

Auth: Required (Retail user)

Request Body:

{
  "projectId": "PJT-101",
  "quantity": 0.25,
  "paymentMethod": "wallet"
}

Response: 200 OK

{
  "orderId": "ORD-789",
  "projectId": "PJT-101",
  "quantity": 0.25,
  "totalPrice": 6.38,
  "status": "Processing",
  "transactionHash": "0x...",
  "createdAt": "2026-01-14T10:00:00Z"
}

---

Retire Credits

POST /retire

Auth: Required (Retail user)

Request Body:

{
  "projectId": "PJT-101",
  "quantity": 0.25,
  "purpose": "Personal offset",
  "message": "Offsetting my carbon footprint"
}

Response: 200 OK

{
  "retirementId": "RET-123",
  "projectId": "PJT-101",
  "quantity": 0.25,
  "transactionHash": "0x...",
  "certificateId": "CERT-456",
  "certificateUri": "https://.../certificate.pdf",
  "retiredAt": "2026-01-14T10:00:00Z"
}

---

Get Certificates

GET /certificates

Auth: Required (Retail user)

Response: 200 OK

{
  "certificates": [
    {
      "id": "CERT-456",
      "projectId": "PJT-101",
      "projectName": "Solar Rajasthan 2024",
      "quantity": 0.25,
      "retirementDate": "2026-01-14T10:00:00Z",
      "certificateUri": "https://.../certificate.pdf",
      "transactionHash": "0x..."
    }
  ]
}

---

Enterprise API

Create Organization

POST /org

Auth: Required

Request Body:

{
  "name": "Acme Corporation",
  "industry": "Technology",
  "location": "United States",
  "taxId": "12-3456789"
}

Response: 201 Created

{
  "id": "ORG-123",
  "name": "Acme Corporation",
  "status": "Setup Incomplete",
  "createdAt": "2026-01-14T10:00:00Z"
}

---

Add Team Member

POST /org/users

Auth: Required (Org Admin)

Request Body:

{
  "email": "[email protected]",
  "role": "Finance",
  "sendInvite": true
}

Response: 201 Created

{
  "userId": "USER-456",
  "email": "[email protected]",
  "role": "Finance",
  "inviteSent": true
}

---

Submit Emissions Data

POST /org/emissions

Auth: Required (Org Admin/Finance)

Request Body:

{
  "period": "2024-Q1",
  "scope1": 5000,
  "scope2": 3000,
  "scope3": 2000,
  "total": 10000
}

Response: 201 Created

{
  "id": "EM-789",
  "period": "2024-Q1",
  "total": 10000,
  "recommendedCredits": 10000,
  "createdAt": "2026-01-14T10:00:00Z"
}

---

Create Retirement Schedule

POST /org/retirement-schedule

Auth: Required (Org Admin/Finance)

Request Body:

{
  "schedule": "Monthly",
  "amount": 1000,
  "startDate": "2026-02-01",
  "projectAllocation": "proportional",
  "approvalRequired": true
}

Response: 201 Created

{
  "id": "SCHED-123",
  "schedule": "Monthly",
  "amount": 1000,
  "status": "Active",
  "nextRetirement": "2026-02-01T00:00:00Z"
}

---

Generate Report

POST /org/reports

Auth: Required (Org Admin/Finance/Auditor)

Request Body:

{
  "reportType": "ESG",
  "period": "2024-Q1",
  "format": "PDF",
  "includeCertificates": true
}

Response: 202 Accepted

{
  "reportId": "REP-456",
  "status": "Generating",
  "estimatedCompletion": "2026-01-14T10:05:00Z"
}

Get Report: GET /org/reports/:id

Response: 200 OK

{
  "id": "REP-456",
  "status": "Ready",
  "downloadUri": "https://.../report.pdf",
  "generatedAt": "2026-01-14T10:05:00Z"
}

---

Indexer API

Get Indexer Status

GET /indexer/status

Response: 200 OK

{
  "status": "Running",
  "lastBlockProcessed": 12345678,
  "currentBlock": 12345680,
  "eventsProcessed": 12345,
  "lastUpdate": "2026-01-14T10:00:00Z"
}

---

Sync Events

POST /indexer/sync/:blockNumber

Auth: Required (Admin)

Response: 200 OK

{
  "blockNumber": 12345678,
  "eventsProcessed": 10,
  "syncedAt": "2026-01-14T10:00:00Z"
}

---

Error Responses

All endpoints may return standard error responses:

400 Bad Request:

{
  "error": "Invalid request",
  "message": "Quantity must be greater than 0",
  "code": "INVALID_QUANTITY"
}

401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "Authentication required",
  "code": "AUTH_REQUIRED"
}

403 Forbidden:

{
  "error": "Forbidden",
  "message": "Insufficient permissions",
  "code": "INSUFFICIENT_PERMISSIONS"
}

404 Not Found:

{
  "error": "Not found",
  "message": "Project not found",
  "code": "PROJECT_NOT_FOUND"
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "message": "An unexpected error occurred",
  "code": "INTERNAL_ERROR"
}

---

Rate Limiting

API requests are rate-limited:

• Default: 100 requests per minute per user

• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset