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

Previous13 smart contract modules Next15 contract architecture

Last updated 3 hours ago

Good morning

hashtagOverview

hashtagBase URL

hashtagAuthentication

hashtagProjects API

hashtagCreate Project

hashtagList Projects

hashtagGet Project Details

hashtagUpload Project Document

hashtagSubmit for PoAI

hashtagGet PoAI Status

hashtagPoAI API

hashtagList PoAI Cases

hashtagGet PoAI Case Details

hashtagAdd/Update PoAI Check

hashtagApprove PoAI Case

hashtagRetail API

hashtagGet Holdings

hashtagPurchase Credits

hashtagRetire Credits

hashtagGet Certificates

hashtagEnterprise API

hashtagCreate Organization

hashtagAdd Team Member

hashtagSubmit Emissions Data

hashtagCreate Retirement Schedule

hashtagGenerate Report

hashtagIndexer API

hashtagGet Indexer Status

hashtagSync Events

hashtagError Responses

hashtagRate Limiting

Overview

Base URL

Authentication

Projects API

Create Project

List Projects

Get Project Details

Upload Project Document

Submit for PoAI

Get PoAI Status

PoAI API

List PoAI Cases

Get PoAI Case Details

Add/Update PoAI Check

Approve PoAI Case

Retail API

Get Holdings

Purchase Credits

Retire Credits

Get Certificates

Enterprise API

Create Organization

Add Team Member

Submit Emissions Data

Create Retirement Schedule

Generate Report

Indexer API

Get Indexer Status

Sync Events

Error Responses

Rate Limiting