IndiCarbon AIIndiCarbon AI
For Developers

Integration Guide

Everything you need to connect IndiCarbon AI to your existing tools — REST API, MCP server, and AI agent workflows.

API v1MCP 1.0JWT AuthOpenAPI 3.1

Overview

IndiCarbon AI exposes its full platform through a single API Gateway at http://localhost:8000 (or your cloud endpoint). All routes are prefixed with /api/v1/.

Auth Service

JWT login, RBAC roles, org management

/api/v1/auth/*
Compliance Service

GHG reporting, BRSR, emission factors

/api/v1/emissions/*
Marketplace Service

Carbon credits, buy/sell orders, trades

/api/v1/orders/*
AI Agent Service

Auditor & Strategist agents, document analysis

/api/v1/ai/*

The full OpenAPI spec is available at http://localhost:8000/api/docs (Swagger UI) and /api/redoc (ReDoc).

Authentication

IndiCarbon uses JWT bearer tokens issued by Supabase Auth. Every protected endpoint requires an Authorization: Bearer <token> header.

1. Login and get token

bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "yourpassword"}'
json
{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": "uuid-here",
    "email": "you@company.com",
    "roles": ["ORG_ADMIN"],
    "is_internal": false
  },
  "message": "Login successful."
}

2. Use the token

bash
# Store the token
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Use it in every subsequent request
curl http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN"

Token lifecycle

  • • Access tokens expire after 1 hour.
  • • Use POST /api/v1/auth/refresh with the refresh token to get a new pair.
  • • Refresh tokens expire after 7 days.
  • • The MCP server handles refresh automatically — no manual intervention needed.

RBAC Roles

Role-based access control governs what each user can do. Roles are assigned per-organisation.

RolePermissions
SUPER_ADMINFull platform access, sector benchmarks, internal tooling
ORG_ADMINManage users, org settings, all compliance & marketplace ops
AUDITORVerify documents, review HITL flags, read all org data
ANALYSTSubmit emission reports, upload documents, read marketplace
TRADERPlace and cancel marketplace orders, view credits
VIEWERRead-only access to org data

MCP Server

The IndiCarbon MCP (Model Context Protocol) server exposes every platform capability as AI-callable tools. Connect it to Claude, and the AI can perform end-to-end carbon accounting workflows through natural language.

Add to Claude Desktop / Cursor / Any MCP Client

The IndiCarbon MCP server is hosted — no local installation required. Add this to your MCP config (e.g. claude_desktop_config.json):

json
{
  "mcpServers": {
    "indicarbon": {
      "url": "https://indicarbon.ajayv.online/mcp/",
      "headers": {
        "x-user-email": "your@email.com",
        "x-user-password": "yourpassword"
      }
    }
  }
}

How authentication works

  • • Your email and password are sent as headers on the initial MCP connection.
  • • The server authenticates against IndiCarbon's auth service and issues a JWT session.
  • • All subsequent tool calls in the session use the JWT — credentials are not resent.
  • • Token refresh is handled automatically by the server.

Restart your AI client after saving. The 30 IndiCarbon tools will appear automatically.

Available MCP Tools

Auth

indicarbon_login · indicarbon_register · indicarbon_get_profile · indicarbon_list_users · indicarbon_list_roles · indicarbon_create_role · indicarbon_assign_role

Organisations

indicarbon_create_organization · indicarbon_list_organizations · indicarbon_get_organization

Documents

indicarbon_register_document · indicarbon_list_documents · indicarbon_get_document · indicarbon_verify_document · indicarbon_get_document_signed_url

Emissions

indicarbon_submit_emission_report · indicarbon_get_emission_summary · indicarbon_generate_brsr_report · indicarbon_list_emission_factors · indicarbon_calculate_scope_emissions · indicarbon_list_sector_benchmarks

Marketplace

indicarbon_list_carbon_credits · indicarbon_get_market_book · indicarbon_list_orders · indicarbon_place_order · indicarbon_cancel_order · indicarbon_retire_credits · indicarbon_list_trades

AI Agents

indicarbon_run_agent · indicarbon_analyse_document · indicarbon_chat_with_agent · indicarbon_get_chat_history · indicarbon_list_agent_registry · indicarbon_create_hitl_review · indicarbon_resolve_hitl_review

API Reference

POST/api/v1/emissionsSubmit Emission Report

Submit a GHG emission data entry. System auto-calculates tCO₂e using India-specific emission factors.

json
{
  "organization_id": "uuid",
  "scope_type": "SCOPE_2",
  "raw_quantity": 150000,
  "activity_unit": "kWh",
  "reporting_period_start": "2024-04-01",
  "reporting_period_end": "2025-03-31",
  "factor_key": "GRID_ELECTRICITY_IN"
}
POST/api/v1/ordersPlace Carbon Credit Order

Place a BUY or SELL order. Auto-matches against counterparties. Returns trade receipt if matched.

json
{
  "organization_id": "uuid",
  "order_type": "BUY",
  "quantity": 500,
  "price_per_unit": "1500.00",
  "vintage_year": 2024,
  "project_type": "solar"
}
POST/api/v1/analyse-documentAnalyse Document with AI

AI-powered extraction of emission data from sustainability reports, annual reports, and energy audits.

json
{
  "organization_id": "uuid",
  "document_id": "uuid"
}
GET/api/v1/emissions/brsrGenerate BRSR Report

Generate SEBI BRSR-compliant GHG disclosure for a reporting period.

bash
?period_start=2024-04-01&period_end=2025-03-31&revenue_crore=4200

Full OpenAPI spec: http://localhost:8000/api/docs

Common Workflows

1. Annual Report → BRSR Compliance (via Claude + MCP)

  1. 1indicarbon_login — Authenticate with org credentials
  2. 2indicarbon_list_organizations — Get your organisation UUID
  3. 3indicarbon_register_document — Register your uploaded annual report (file_path from Supabase Storage)
  4. 4indicarbon_analyse_document — AI extracts emission line items, calculates scope totals, saves to DB
  5. 5indicarbon_get_emission_summary — Review Scope 1 + 2 + 3 totals
  6. 6indicarbon_generate_brsr_report — Generate the SEBI BRSR disclosure

2. Carbon Credit Trading

  1. 1indicarbon_get_market_book — View all open SELL orders — price, vintage, project type
  2. 2indicarbon_place_order (BUY) — Place a buy order; auto-matches if a SELL exists at your price
  3. 3indicarbon_list_orders — Confirm order status (OPEN → FILLED)
  4. 4indicarbon_list_carbon_credits — Verify credits transferred to your org
  5. 5indicarbon_retire_credits — Retire credits to offset your calculated emissions

SDKs & Tools

Python MCP Server

Full MCP server for AI agent integration. Works with Claude Desktop, Claude Code, and any MCP-compatible host.

D:\IndiCarbon\mcp-server
REST API

Full OpenAPI 3.1 spec. Use any HTTP client — curl, httpx, axios. Rate limit: 100 req/min per IP.

http://localhost:8000/api/docs
AI Agents

Auditor and Strategist LangChain ReAct agents with Langfuse observability and HITL safety guardrails.

/api/v1/ai/run
Webhook Events

Coming soon — subscribe to trade settled, document verified, and emission threshold breach events.

—

Error Handling

All API responses follow the ApiResponse envelope:

json
// Success
{ "data": { ... }, "message": "Operation successful." }

// Error
{ "data": null, "error": "Detailed error message", "error_code": 422 }
StatusMeaning & Action
401Token missing or expired → call /auth/refresh
403Insufficient role → check your RBAC permissions
404Resource not found → verify UUIDs
422Validation error → check request body schema
429Rate limited → back off for 60 seconds
503Downstream service unavailable → retry with exponential backoff

Ready to integrate?

Clone the repo, start the Docker stack, and you'll have a full IndiCarbon environment running in under 10 minutes.