Greenwashing API Integration Guide for Developers

The GreenClaims Scanner greenwashing API lets you programmatically check environmental claims against the EU Green Claims Directive (ECGT) rule set before content is published — inside your CMS workflow, your CI/CD pipeline, or your ad copy review system. This guide covers authentication, endpoints, request/response formats, and working code examples in Python, Node.js, and PHP.

To get an API key, sign up for a paid plan. The REST API is available on all plans above the free tier.

Why Integrate the API?

Running scans manually after content is published means violations are already live when you catch them. Integrating the greenwashing API into your content workflow means:

• Claims are checked at authoring time — before any human or automated review approves them
• Your CMS can display inline warnings to copywriters as they draft
• Your CI/CD pipeline can fail a deploy if new high-risk claims are detected
• Your ad platform integration can block ad copy that would trigger an ECGT violation before it goes to review

For teams publishing at high volume — e-commerce product pages, multi-language campaigns — this is the only practical way to maintain ECGT compliance at scale. See our article on automated greenwashing monitoring for the broader business case.

API Overview

Attribute	Value
Base URL	https://api.greenclaims-scanner.com/v1
Authentication	Bearer token (API key in Authorization header)
Request format	JSON (POST body) or query string (GET)
Response format	JSON
Rate limit	100 requests/minute (Starter); 1,000/minute (Pro); custom (Enterprise)
Latency	p50: 180ms; p95: 450ms

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are available in your dashboard after signing up. Never expose your API key in client-side JavaScript or commit it to a public repository. Use environment variables.

Core Endpoints

POST /v1/scan/text — Scan a text string

The most common endpoint. Submit any text string — product description, ad copy, email subject line — and receive a risk score with flagged claims.

Request:

POST https://api.greenclaims-scanner.com/v1/scan/text
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "text": "Our eco-friendly packaging is made from sustainable materials and is 100% carbon neutral.",
  "locale": "en",
  "context": "product_description"
}

Response:

{
  "scan_id": "scn_01hx4p2k3m",
  "risk_score": 87,
  "risk_level": "high",
  "violations": [
    {
      "term": "eco-friendly",
      "type": "banned_vague_claim",
      "severity": "high",
      "position": {"start": 4, "end": 15},
      "ecgt_article": "Annex I, para 1",
      "recommendation": "Replace with specific environmental attribute. Example: 'packaging made from 80% post-consumer recycled cardboard'"
    },
    {
      "term": "sustainable materials",
      "type": "vague_general_claim",
      "severity": "high",
      "position": {"start": 44, "end": 63},
      "ecgt_article": "Art. 3(1)(a)",
      "recommendation": "Specify materials, percentages, and certification."
    },
    {
      "term": "carbon neutral",
      "type": "restricted_requires_substantiation",
      "severity": "high",
      "position": {"start": 76, "end": 89},
      "ecgt_article": "Annex I, para 2",
      "recommendation": "Remove or replace with scoped, verified emission reduction data."
    }
  ],
  "compliant_claims": [],
  "processing_ms": 142
}

POST /v1/scan/url — Scan a URL

Submit a URL and the API fetches, parses, and scans the page content. Useful for CI/CD integration where you want to scan a staging URL before deploying to production.

POST https://api.greenclaims-scanner.com/v1/scan/url
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://staging.example.com/products/eco-range",
  "include_meta": true
}

GET /v1/rules — List all active rules

Returns the full list of active ECGT rules with their IDs, categories, and severity levels. Useful for building custom filtering logic or for documentation.

GET https://api.greenclaims-scanner.com/v1/rules?locale=en
Authorization: Bearer YOUR_API_KEY

Code Examples

Python

import requests
import os

API_KEY = os.environ["GREENCLAIMS_API_KEY"]
BASE_URL = "https://api.greenclaims-scanner.com/v1"

def check_claim(text: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/scan/text",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "text": text,
            "locale": "en",
            "context": "product_description",
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

# Example usage
result = check_claim("Our sustainable packaging is eco-friendly.")
if result["risk_level"] in ("medium", "high"):
    print(f"⚠️  Risk score {result['risk_score']}: {len(result['violations'])} violation(s) found")
    for v in result["violations"]:
        print(f"  - [{v['severity'].upper()}] '{v['term']}': {v['recommendation']}")
else:
    print("✅ No violations detected")

Node.js

const fetch = require("node-fetch"); // or use built-in fetch in Node 18+

const API_KEY = process.env.GREENCLAIMS_API_KEY;
const BASE_URL = "https://api.greenclaims-scanner.com/v1";

async function checkClaim(text) {
  const response = await fetch(`${BASE_URL}/scan/text`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text,
      locale: "en",
      context: "product_description",
    }),
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage in a CMS save hook
async function onContentSave(content) {
  const result = await checkClaim(content.environmentalClaims);
  if (result.risk_level === "high") {
    throw new Error(
      `Content blocked: ${result.violations.length} greenwashing violation(s). ` +
      `Risk score: ${result.risk_score}/100`
    );
  }
  return content;
}

PHP

<?php

function checkGreenwashingClaim(string $text): array {
    $apiKey = getenv('GREENCLAIMS_API_KEY');
    $url = 'https://api.greenclaims-scanner.com/v1/scan/text';

    $payload = json_encode([
        'text' => $text,
        'locale' => 'en',
        'context' => 'product_description',
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
        ],
        CURLOPT_TIMEOUT => 10,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new RuntimeException('GreenClaims API error: ' . $httpCode);
    }

    return json_decode($response, true);
}

// WordPress integration example (pre_post_update hook)
add_action('pre_post_update', function(int $postId, array $data) {
    $text = wp_strip_all_tags($data['post_content']);
    $result = checkGreenwashingClaim($text);
    if ($result['risk_level'] === 'high') {
        wp_die('Content blocked: greenwashing violations detected. Please review and resubmit.');
    }
}, 10, 2);

CI/CD Integration Example (GitHub Actions)

name: Greenwashing Compliance Check

on:
  pull_request:
    paths:
      - 'content/**'
      - 'src/pages/**'

jobs:
  greenwashing-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan changed content files
        env:
          GREENCLAIMS_API_KEY: ${{ secrets.GREENCLAIMS_API_KEY }}
        run: |
          pip install requests
          python scripts/scan_content.py --changed-only --fail-on=high

Webhook Notifications

For continuous monitoring integrations, GreenClaims Scanner supports webhooks. Configure a webhook URL in your dashboard and receive a POST notification whenever a new violation is detected on a monitored domain:

{
  "event": "violation_detected",
  "domain": "example.com",
  "page_url": "https://example.com/products/new-range",
  "scan_id": "scn_01hx5r2m4n",
  "risk_level": "high",
  "violation_count": 2,
  "detected_at": "2026-03-12T09:14:22Z"
}

Error Handling

HTTP Status	Meaning	Recommended Action
200	Success	Process response normally
400	Invalid request (malformed JSON, missing required field)	Check request format
401	Invalid or missing API key	Check Authorization header
429	Rate limit exceeded	Implement exponential backoff; consider upgrading plan
500	Server error	Retry after 30 seconds; if persistent, contact support

Getting Started

Sign up for a plan to get your API key, or scan your website free first to understand your current compliance posture before integrating. Full API reference documentation is available in the developer portal after signup.