SustainBuddy API Documentation

🌊 Overview

The SustainBuddy Maritime Sustainability API provides access to expert maritime sustainability consulting services through an AI-powered conversational interface. Get guidance on emissions reduction, regulatory compliance, carbon credits, and sustainable shipping practices.

🚢 Maritime Expertise

Specialized knowledge in shipping sustainability, emissions reduction, and maritime regulations.

💬 Conversational AI

Maintains conversation context across multiple interactions for detailed consultations.

📚 Document-Backed

Responses include citations from authoritative maritime sustainability documents.

🏢 Partner Integration

Direct connections to VERTIS, Climate Balanced, and VURDHAAN for professional services.

Base URL

https://api.sustainbuddy.ai

Supported Regulatory Frameworks

EU MRV (Monitoring, Reporting, Verification)
EU ETS (Emissions Trading System)
UK MRV
IMO DCS (Data Collection System)
FuelEU Maritime

🔐 Authentication

Currently, the API does not require authentication for basic usage. All endpoints are publicly accessible for maritime sustainability consultations.

# No authentication required
curl -X GET https://api.sustainbuddy.ai/health
                

🛠️ API Endpoints

GET /health

Check the health and status of the SustainBuddy API service.

Response

{
  "status": "healthy",
  "timestamp": "2025-07-28T12:34:56.789Z",
  "service": "Maritime Sustainability Chatbot"
}
                        

200 - OK

Service is healthy and operational

POST /chat

Send a message to the maritime sustainability consultant and receive expert guidance with source citations.

Request Parameters

Parameter	Type	Required	Description
`message`	string	Required	Your maritime sustainability question or request
`previous_response_id`	string	Optional	ID from previous response to continue conversation

Request Example

{
  "message": "What are the main strategies for reducing carbon emissions in shipping?",
  "previous_response_id": "resp_abc123..."
}
                        

Response

{
  "success": true,
  "response": {
    "answer": "Shipping companies can reduce carbon emissions through several key strategies including alternative fuels, energy efficiency improvements, operational optimizations, and regulatory compliance measures...",
    "source_quote": "Alternative fuels such as ammonia and hydrogen offer significant potential for emissions reduction in maritime transport.",
    "source_file": "maritime_sustainability_guide.pdf",
    "source_quote_location": {
      "page": 15,
      "line": 23
    }
  },
  "response_id": "resp_def456...",
  "is_new_conversation": false,
  "timestamp": "2025-07-28T12:34:56.789Z"
}
                        

200 - OK

Successful response with maritime consultation

400 - Bad Request

Missing or empty message parameter

500 - Internal Server Error

Service error or AI processing failure

POST /new-conversation

Start a new conversation session. This is a convenience endpoint to signal a fresh consultation.

Response

{
  "success": true,
  "message": "Ready for new conversation. Send your first message to /chat without previous_response_id.",
  "timestamp": "2025-07-28T12:34:56.789Z"
}
                        

200 - OK

New conversation session ready

💡 Usage Examples

Starting a New Conversation

curl -X POST https://api.sustainbuddy.ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the EU ETS for shipping?"
  }'
                

Continuing a Conversation

curl -X POST https://api.sustainbuddy.ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How does this compare to IMO regulations?",
    "previous_response_id": "resp_abc123..."
  }'
                

JavaScript Integration

class SustainBuddyClient {
  constructor(apiUrl = 'https://api.sustainbuddy.ai') {
    this.apiUrl = apiUrl;
    this.currentResponseId = null;
  }

  async sendMessage(message) {
    const payload = { message };
    
    if (this.currentResponseId) {
      payload.previous_response_id = this.currentResponseId;
    }

    const response = await fetch(`${this.apiUrl}/chat`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });

    const data = await response.json();
    
    if (data.success) {
      this.currentResponseId = data.response_id;
      return data.response;
    } else {
      throw new Error(data.error);
    }
  }

  newConversation() {
    this.currentResponseId = null;
  }
}

// Usage
const client = new SustainBuddyClient();

// Start conversation
const response1 = await client.sendMessage("What is FuelEU Maritime?");
console.log(response1.answer);

// Continue conversation
const response2 = await client.sendMessage("What are the compliance requirements?");
console.log(response2.answer);
                

Python Integration

import requests
import json

class SustainBuddyClient:
    def __init__(self, api_url="https://api.sustainbuddy.ai"):
        self.api_url = api_url
        self.current_response_id = None
    
    def send_message(self, message):
        payload = {"message": message}
        
        if self.current_response_id:
            payload["previous_response_id"] = self.current_response_id
        
        response = requests.post(
            f"{self.api_url}/chat",
            json=payload,
            headers={"Content-Type": "application/json"}
        )
        
        data = response.json()
        
        if data["success"]:
            self.current_response_id = data["response_id"]
            return data["response"]
        else:
            raise Exception(data["error"])
    
    def new_conversation(self):
        self.current_response_id = None

# Usage
client = SustainBuddyClient()

# Start conversation
response1 = client.send_message("What are carbon credits for shipping?")
print(response1["answer"])

# Continue conversation
response2 = client.send_message("How do I get VERTIS credits?")
print(response2["answer"])
                

⚠️ Error Handling

The SustainBuddy API uses conventional HTTP response codes to indicate the success or failure of API requests.

Error Response Format

{
  "error": "Description of the error",
  "success": false,
  "timestamp": "2025-07-28T12:34:56.789Z"
}
                

HTTP Status Codes

200 - OK

Request was successful

400 - Bad Request

The request was invalid or cannot be served

404 - Not Found

The requested endpoint does not exist

405 - Method Not Allowed

The request method is not supported for this endpoint

500 - Internal Server Error

Something went wrong on our end

Common Error Scenarios

Error	Status	Description
Missing 'message' in request body	400	The message parameter is required for chat requests
Empty message provided	400	The message cannot be empty or contain only whitespace
Internal server error occurred	500	AI processing error or service unavailability

Best Practices

Always check the success field in the response
Implement proper error handling for network failures
Store response_id values for conversation continuity
Handle rate limiting gracefully (if implemented)
Validate input messages before sending requests