API Documentation

Integrate our simple and powerful API to start planting trees with just a few lines of code. Our RESTful API allows you to plant trees, track your impact, and contribute to global reforestation efforts programmatically.

Base URL: https://api.webuildforest.example.com/v1

Introduction

Welcome to the We Build Forest API! Our API is designed to be simple, intuitive, and powerful, enabling developers to seamlessly integrate tree planting into their applications, websites, and services.

Whether you want to reward users, offset carbon footprints, or run environmental campaigns, our API provides the tools you need. This documentation will guide you through authentication, available endpoints, request/response formats, and error handling.

For a hands-on start, check out our Quickstart Guide below.

Authentication

All API requests must be authenticated using a Bearer Token. You can obtain your API key from your dashboard after signing up.

Include your API key in the Authorization header of your requests:

HTTP
Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual secret API key. Keep your API key confidential and secure.

Quickstart Guide

Ready to plant your first tree via API? Here's how to do it in under 5 minutes:

  • Sign Up: If you haven't already, create your We Build Forest account.
  • Get API Key: Navigate to your API Keys page in the dashboard and generate a new secret key.
  • Choose a Project: Browse our planting projects to find one you'd like to support. Note its ID (e.g., 'amazon_regeneration_project_xyz').
  • Make Your First Call: Use the POST /trees endpoint with your API key and chosen project ID. See example below.

Example: Plant 1 Tree (cURL)

bash
curl -X POST "https://api.webuildforest.example.com/v1/trees" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "project_id": "amazon_regeneration_project_xyz",
       "quantity": 1,
       "user_identifier": "quickstart_user_01"
     }'

Check your dashboard - you should see your tree recorded! You can now integrate this into your application logic.

API Endpoints

POST/trees

Plant one or more trees.

Creates a request to plant a specified number of trees in a chosen project. This is the primary endpoint for initiating tree planting.

Parameters

NameInTypeDescription
project_id*bodystringThe ID of the planting project. Find project IDs on our Projects page or via a future API endpoint.
quantity*bodyintegerThe number of trees to plant. Must be a positive integer.
user_identifierbodystringAn optional identifier for the user or entity on whose behalf the tree is planted (e.g., customer ID, employee ID).
metadatabodyobjectOptional. A flat object for storing custom key-value pairs related to this planting request (e.g., order_id, campaign_name). Max 5 keys.

Example Request

json
{
  "project_id": "amazon_regeneration_project_xyz",
  "quantity": 1,
  "user_identifier": "customer_12345",
  "metadata": {
    "order_id": "ORD-2023-ABC",
    "campaign": "EarthMonth2023"
  }
}

Example Response (200 OK)

json
{
  "success": true,
  "message": "Tree planting request received successfully.",
  "planting_request_id": "pr_1a2b3c4d5e6f7g8h9i",
  "trees_requested": 1,
  "project_id": "amazon_regeneration_project_xyz",
  "status": "pending_verification"
}

GET/trees/{tree_id}

Retrieve information about a specific planted tree or planting request.

Fetches details for a specific tree or the status of a planting request using its unique ID. (Note: This endpoint is illustrative for a detailed tree object. For `planting_request_id` from the POST /trees response, you might have a `/planting-requests/{request_id}` endpoint in a full API.)

Parameters

NameInTypeDescription
tree_id*pathstringThe unique identifier of the tree or planting request.

Example Response (200 OK)

json
{
  "id": "tree_9z8y7x6w5v4u3t2s",
  "project_id": "amazon_regeneration_project_xyz",
  "project_name": "Amazon Rainforest Restoration",
  "species_planted": "Bertholletia excelsa (Brazil Nut)",
  "location_coordinates": {
    "latitude": -3.4653,
    "longitude": -62.2159
  },
  "planted_date": "2023-11-15T10:30:00Z",
  "user_identifier": "customer_12345",
  "status": "planted_and_verified",
  "certificate_url": "https://webuildforest.example.com/certificates/tree_9z8y7x6w5v4u3t2s"
}

GET/me/balance

Check your account balance or tree credits.

Retrieves the current balance of pre-purchased tree credits or API call units for your account.

Example Response (200 OK)

json
{
  "account_id": "acc_user01",
  "plan_type": "Adopt Trees (Bulk)",
  "tree_credits_remaining": 75,
  "api_calls_this_month": 120,
  "monthly_api_limit": 10000
}

Rate Limiting

To ensure fair usage and stability, our API employs rate limiting. The specific limits depend on your chosen plan.

  • Free/Trial Tier: 100 requests per hour.
  • Standard API Plan: 1,000 requests per hour.
  • Bulk/Enterprise Plan: Custom limits, typically 10,000+ requests per hour.

If you exceed these limits, you will receive a 429 Too Many Requests HTTP status code. Response headers will indicate when you can retry:

HTTP Headers
Retry-After: 60 (seconds)
X-RateLimit-Limit: 1000 (requests per hour)
X-RateLimit-Remaining: 0 (requests remaining in current window)

Error Codes

Our API uses standard HTTP status codes to indicate the success or failure of a request. Here are some common error codes:

  • 400 Bad Request: The request was improperly formatted, or a required parameter was missing. The response body will contain more details.
  • 401 Unauthorized: Your API key is missing, invalid, or expired.
  • 403 Forbidden: Your API key does not have permission to access the requested resource or perform the action.
  • 404 Not Found: The requested resource (e.g., a specific project or tree ID) could not be found.
  • 429 Too Many Requests: You have exceeded your API rate limit.
  • 500 Internal Server Error: Something went wrong on our end. Please try again later. If the problem persists, contact support.

Error responses are typically in JSON format and include a message field with a human-readable explanation of the error.

json
{
  "error": true,
  "status_code": 400,
  "message": "Validation Error: quantity must be a positive integer."
}

Ready to Integrate?

We're excited to see what you build! If you have any questions or need assistance during your integration, don't hesitate to reach out to our support team or consult the FAQ section on our website.

Get Your API Key Now

This API documentation is for demonstration purposes.