API Documentation — Trust Carbon Infrastructure

Authentication

Token-Based Authentication

The Trust Carbon API uses Laravel Sanctum bearer tokens for authentication. Include your API token in the Authorization header of every request.

cURL Example

curl -X GET "https://app.trustcarbon.org/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Generating Tokens

API tokens are provisioned through the Trust Carbon dashboard. Navigate to Settings → API Keys to create and manage your tokens.

Token Security

Tokens are scoped to your organization. Store them securely using environment variables. Never expose tokens in client-side code or version control.

Base URL

API Base URL

All API requests should be made to the following base URL. All responses are returned as JSON.

          Production
        
https://app.trustcarbon.org/api/v1

HTTPS Only

All requests must use HTTPS. HTTP requests are rejected.

JSON Responses

All responses use application/json content type with UTF-8 encoding.

Versioning

API version is included in the URL path. Current stable version is v1.

Endpoints

API Reference

Complete reference for all available endpoints. Click any endpoint to expand details, parameters, and example responses.

Projects Manage carbon verification projects

GET /projects List all projects

Returns a paginated list of all carbon verification projects within your organization. Supports filtering by status, region, and creation date.

Parameter	Type	Required	Description
page	integer	optional	Page number for pagination
per_page	integer	optional	Results per page (default: 20, max: 100)
status	string	optional	Filter by status: active, pending, completed

Example Response — 200 OK

JSON

{
  "data": [
    {
      "id": 142,
      "name": "Amazon Reforestation Alpha",
      "status": "active",
      "total_area_ha": 2450.8,
      "carbon_estimated_tons": 18420.5,
      "country": "BR",
      "created_at": "2025-11-15T08:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 47,
    "per_page": 20
  }
}

GET /projects/{id} Get project details

Retrieve detailed information about a specific project, including areas, verification status, and carbon analysis summary.

Example Response — 200 OK

JSON

{
  "data": {
    "id": 142,
    "name": "Amazon Reforestation Alpha",
    "status": "active",
    "total_area_ha": 2450.8,
    "areas_count": 12,
    "carbon_estimated_tons": 18420.5,
    "verification_status": "verified",
    "country": "BR",
    "state": "PA",
    "created_at": "2025-11-15T08:30:00Z",
    "updated_at": "2026-01-20T14:15:00Z"
  }
}

POST /projects Create a new project

Create a new carbon verification project. Requires a project name, country code, and at least one geographic area.

Parameter	Type	Required	Description
name	string	required	Project name (max 255 characters)
country	string	required	ISO 3166-1 alpha-2 country code
state	string	optional	State or region code
description	string	optional	Project description

Example Response — 201 Created

JSON

{
  "data": {
    "id": 143,
    "name": "Cerrado Conservation Beta",
    "status": "pending",
    "country": "BR",
    "created_at": "2026-03-24T10:00:00Z"
  },
  "message": "Project created successfully"
}

Areas Geographic areas within projects

GET /projects/{id}/areas List project areas

Returns all geographic areas associated with a project, including GeoJSON boundaries, vegetation data, and carbon estimates per area.

Example Response — 200 OK

JSON

{
  "data": [
    {
      "id": 301,
      "project_id": 142,
      "name": "Sector A - Dense Forest",
      "area_ha": 540.2,
      "vegetation_type": "tropical_rainforest",
      "carbon_tons": 4215.0,
      "coordinates": {
        "type": "Polygon",
        "coordinates": [/* GeoJSON */]
      }
    }
  ]
}

POST /projects/{id}/areas Create a new area

Add a geographic area to a project. Accepts GeoJSON polygon coordinates and optional vegetation metadata.

Parameter	Type	Required	Description
name	string	required	Area name
coordinates	object	required	GeoJSON Polygon geometry
vegetation_type	string	optional	Vegetation classification

Example Response — 201 Created

JSON

{
  "data": {
    "id": 302,
    "project_id": 142,
    "name": "Sector B - Riparian Zone",
    "area_ha": 320.5,
    "status": "pending_analysis"
  }
}

Data Collections Field data and measurements

GET /project/{id}/data-collections List data collections

Retrieve all field data collections for a project, including species inventories, soil samples, and measurement records.

Example Response — 200 OK

JSON

{
  "data": [
    {
      "id": 891,
      "project_id": 142,
      "type": "species_inventory",
      "collected_at": "2026-02-10T09:00:00Z",
      "records_count": 234,
      "status": "validated"
    }
  ]
}

POST /data-collections Submit new data collection

Submit field-collected data including species counts, tree measurements (DAP/height), and soil samples. Data is validated and queued for processing.

Parameter	Type	Required	Description
project_id	integer	required	Target project ID
area_id	integer	required	Target area ID
type	string	required	Collection type: species_inventory, soil_sample, tree_measurement
records	array	required	Array of measurement records

Example Response — 201 Created

JSON

{
  "data": {
    "id": 892,
    "status": "processing",
    "records_received": 156
  },
  "message": "Data collection submitted for validation"
}

Carbon Analysis Carbon quantification and fire detection

POST /carbon/analysis/fire Run fire risk analysis

Trigger a fire risk analysis for a given geographic area using satellite thermal data and historical fire patterns. Returns risk scores and affected zones.

Parameter	Type	Required	Description
area_id	integer	required	Area ID to analyze
date_range	object	optional	Start/end dates for historical analysis

Example Response — 200 OK

JSON

{
  "data": {
    "analysis_id": "fa-2026-0324-001",
    "risk_score": 0.23,
    "risk_level": "low",
    "hotspots_detected": 0,
    "last_fire_event": null,
    "analyzed_at": "2026-03-24T12:00:00Z"
  }
}

GET /carbon/checkpoints List carbon checkpoints

Retrieve all carbon quantification checkpoints. Checkpoints represent verified snapshots of carbon stock at specific points in time.

Example Response — 200 OK

JSON

{
  "data": [
    {
      "id": 55,
      "project_id": 142,
      "carbon_tons": 18420.5,
      "methodology": "AR-ACM0003",
      "verified": true,
      "checkpoint_date": "2026-01-15T00:00:00Z"
    }
  ]
}

Land Registry Land ownership and CAR verification

GET /land/search/area Search by geographic area

Search the land registry (CAR - Cadastro Ambiental Rural) by geographic coordinates or bounding box. Returns matching property records with boundaries.

Parameter	Type	Required	Description
lat	float	required	Latitude coordinate
lng	float	required	Longitude coordinate
radius_km	float	optional	Search radius in km (default: 10)

Example Response — 200 OK

JSON

{
  "data": [
    {
      "car_code": "PA-1500602-F0A1B2C3",
      "property_name": "Fazenda Verde Esperanca",
      "area_ha": 1850.4,
      "municipality": "Altamira",
      "state": "PA",
      "status": "active"
    }
  ]
}

GET /land/search/owner Search by owner

Search the land registry by owner name or document number (CPF/CNPJ). Returns all matching properties.

Parameter	Type	Required	Description
query	string	required	Owner name or document number
state	string	optional	Filter by state code

Example Response — 200 OK

JSON

{
  "data": [
    {
      "car_code": "PA-1500602-F0A1B2C3",
      "owner": "Agropecuaria Verde Ltda",
      "area_ha": 1850.4,
      "state": "PA",
      "properties_count": 3
    }
  ]
}

Statistics Aggregated project analytics

GET /projects/{id}/stats/species-per-area Species distribution by area

Returns aggregated species counts and biodiversity metrics for each area within a project. Useful for ecological reports and verification audits.

Example Response — 200 OK

JSON

{
  "data": {
    "project_id": 142,
    "total_species": 87,
    "areas": [
      {
        "area_id": 301,
        "area_name": "Sector A - Dense Forest",
        "species_count": 54,
        "shannon_index": 3.42,
        "dominant_species": "Bertholletia excelsa"
      }
    ]
  }
}

Satellite Satellite imagery and NDVI analysis

POST /satellite/start Start satellite analysis

Initiate an asynchronous satellite analysis job for a geographic area. Processes multispectral imagery for NDVI, deforestation detection, and land-use classification. Returns a job ID for polling.

Parameter	Type	Required	Description
area_id	integer	required	Area ID to analyze
analysis_type	string	optional	Type: ndvi, deforestation, land_use (default: all)
date_range	object	optional	Start/end dates for imagery window

Example Response — 202 Accepted

JSON

{
  "data": {
    "analysis_id": "sat-2026-0324-a7f3",
    "status": "queued",
    "estimated_completion": "2026-03-24T12:15:00Z",
    "poll_url": "/api/v1/satellite/analysis/sat-2026-0324-a7f3"
  }
}

GET /satellite/analysis/{id} Get analysis results

Retrieve the results of a satellite analysis job. Returns NDVI values, deforestation alerts, and classified imagery data when the job is complete.

Example Response — 200 OK

JSON

{
  "data": {
    "analysis_id": "sat-2026-0324-a7f3",
    "status": "completed",
    "ndvi_mean": 0.82,
    "ndvi_min": 0.45,
    "ndvi_max": 0.94,
    "deforestation_detected": false,
    "land_use": {
      "forest": 78.4,
      "agriculture": 12.1,
      "water": 6.2,
      "other": 3.3
    },
    "imagery_date": "2026-03-20T10:30:00Z"
  }
}

Export Data export and reporting

GET /export-data/project/{id} Export project data

Export comprehensive project data including all areas, data collections, carbon analyses, and verification records. Supports multiple output formats.

Parameter	Type	Required	Description
format	string	optional	Output format: json, csv, xlsx, geojson (default: json)
include	string	optional	Comma-separated: areas, collections, carbon, satellite

Example Response — 200 OK

JSON

{
  "data": {
    "export_id": "exp-142-20260324",
    "format": "json",
    "download_url": "/api/v1/exports/exp-142-20260324/download",
    "expires_at": "2026-03-25T12:00:00Z",
    "size_bytes": 2458624
  }
}

Rate Limits

Rate Limiting

API requests are rate-limited based on your subscription tier. Exceeding limits returns a 429 Too Many Requests response with a Retry-After header.

Tier	Requests / Minute	Requests / Day	Satellite Jobs / Day	Export / Day
Free	30	1,000	5	10
Professional	120	10,000	50	100
Enterprise	600	100,000	Unlimited	Unlimited

Rate Limit Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1711296000
          

Webhooks

Webhook Events

Subscribe to real-time event notifications. Webhooks are sent as POST requests to your configured endpoint with a signed payload.

satellite.analysis.completed

Fired when a satellite analysis job finishes processing. Includes the full analysis results in the payload.

carbon.fire.alert

Real-time fire detection alert. Triggered when thermal anomalies are detected within your monitored areas.

project.verification.updated

Fired when a project's verification status changes. Includes previous and new status in the payload.

export.ready

Triggered when an export job completes. Includes a temporary download URL valid for 24 hours.

Webhook Payload Example

{
  "event": "satellite.analysis.completed",
  "timestamp": "2026-03-24T12:15:00Z",
  "data": {
    "analysis_id": "sat-2026-0324-a7f3",
    "status": "completed",
    "project_id": 142
  },
  "signature": "sha256=a1b2c3d4e5f6..."
}

SDKs & Integration

The Trust Carbon API is a standard REST API. Use any HTTP client in your preferred language to integrate.

REST API

Standard REST API with JSON payloads. Compatible with any language or platform that supports HTTP requests. Use curl, fetch, axios, or any HTTP library.

Official SDKs

Official SDKs for Python, Node.js, and PHP are under development and will be published as open-source packages. Join the waitlist for early access.

OpenAPI Spec

A full OpenAPI 3.0 specification is available for generating client libraries, testing with Postman, and auto-generating documentation.

Trust Carbon API

Token-Based Authentication

Generating Tokens

Token Security

API Base URL

HTTPS Only

JSON Responses

Versioning

API Reference

Rate Limiting

Webhook Events

satellite.analysis.completed

carbon.fire.alert

project.verification.updated

export.ready

SDKs & Integration

REST API

Official SDKs

OpenAPI Spec

Ready to integrate?