v1 API

API Documentation

Everything you need to integrate environmental scoring into your application.

Base URL:https://api.greenmetric.ai

API Reference

Complete reference for all REST API endpoints — analysis, organizations, billing, and more.

SDKs & Libraries

cURL examples and raw HTTP guides to get started. Official SDKs coming soon.

Authentication

Learn how to authenticate API requests using API keys and JWT tokens.

Webhooks

Subscribe to events like analysis.completed, quota.warning, and more.

Quick Start

1. Get your API key

Sign up for a free account and create an API key from the API Keys dashboard. Keys are prefixed gm_live_ for production or gm_test_ for testing.

2. Submit an analysis

Analysis is asynchronous — the API returns 202 Accepted with an analysis ID. Poll GET /v1/analysis/:id until the status is completed.

curl -X POST https://api.greenmetric.ai/v1/analysis/text \
  -H "x-api-key: gm_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Used iPhone 14 Pro Max, excellent condition",
    "destinationCountry": "US"
  }'

3. Parse the response

Once the analysis completes, you get a rich result with scores, environmental impact, EU Green Index, purchase advice, and more.

{
  "success": true,
  "data": {
    "id": "analysis_abc123",
    "status": "completed",
    "product": {
      "name": "iPhone 14 Pro Max",
      "category": "Smartphones",
      "condition": "Excellent"
    },
    "scores": {
      "overallScore": 87,
      "rating": "A+",
      "euGreenIndexScore": 82,
      "durabilityRating": 8,
      "repairabilityScore": 6,
      "reusabilityScore": 9
    },
    "environmentalImpact": {
      "co2SavedKg": 68.0,
      "waterSavedLiters": 11050,
      "energySavedKwh": 245,
      "rawMaterialsSavedKg": 0.18,
      "packagingWasteAvoidedKg": 0.35
    },
    "purchaseRecommendation": {
      "bestChoice": true,
      "reasoning": "...",
      "estimatedSavings": "$580"
    }
  }
}

Analysis Endpoints

Full API Reference →

POST

/v1/analysis/textAnalyze a product from text description (async, returns 202)

POST

/v1/analysis/urlAnalyze a product from an Amazon URL (async, returns 202)

GET

/v1/analysis/:idRetrieve a specific analysis by ID

GET

/v1/analysisList analyses (paginated)

Request Body

Field	Type	Required	Description
`text`	string	/text only	Product description (10–5,000 characters)
`url`	string	/url only	Amazon product URL
`destinationCountry`	string	No	ISO 3166-1 alpha-2 code. Defaults to `"US"`. Supported: US, CN, IN, JP, KR, DE, GB, FR, IT, ES, SE, PT, VN, BD, TW, MX, TH, ID, TR, KH

Authentication

API Keys (recommended for integrations)

Pass your API key in the x-api-key header. Keys are scoped to an organization and can have custom permissions and restrictions.

x-api-key: gm_live_xxxxxxxxxxxx

Key prefixes: gm_live_ for production, gm_test_ for testing. Create and manage keys from the API Keys page.

JWT Bearer Tokens (dashboard sessions)

For browser-based dashboard sessions, the API uses JWT tokens via the Authorization header. Tokens are obtained through the /v1/auth/login endpoint and refreshed via /v1/auth/refresh.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Rate Limits & Quotas

Rate limits are enforced per-organization. When you exceed either limit, the API returns 429 Too Many Requests.

Plan	Rate Limit	Monthly Quota
Free	10 req/min	25/month
Starter	30 req/min	5,000/month
Pro	100 req/min	50,000/month
Enterprise	500 req/min	500,000/month

Response Headers

Every response includes rate limit headers so you can track your usage:

RateLimit-Limit: 100
RateLimit-Remaining: 87
RateLimit-Reset: 1700000060

429 Response Body

When rate limited, the response includes a retryAfter value in seconds. When quota is exceeded, it also includes a usage object:

{
  "success": false,
  "error": "Monthly API call quota exceeded",
  "message": "You have used all 25 analyses for this period.",
  "retryAfter": 60,
  "usage": {
    "used": 25,
    "limit": 25,
    "periodEnd": "2025-02-01T00:00:00.000Z"
  }
}

Webhooks

Receive real-time notifications when events occur in your organization. Configure webhooks from the API Reference or via the dashboard.

Supported Events

Event	Description
`analysis.completed`	An analysis has finished processing successfully
`analysis.failed`	An analysis encountered an error during processing
`quota.warning`	Your organization has used 80% of its monthly quota
`quota.exceeded`	Your organization has reached its monthly quota limit

Webhook Payload

Every webhook delivery is a POST request with a JSON body containing the event type, a timestamp, and the relevant data:

{
  "event": "analysis.completed",
  "timestamp": "2026-02-17T12:00:00.000Z",
  "data": {
    "analysisId": "analysis_abc123",
    "status": "completed",
    "scores": {
      "overallScore": 87,
      "rating": "A+"
    }
  }
}

Managing Webhooks

Use the /v1/organizations/:orgId/webhooks endpoints to create, list, update, and delete webhooks. You can also view delivery history to debug failed deliveries. See the full API Reference for details.

Error Handling

All errors follow a consistent JSON format. Every response includes a requestId for debugging — quote it when contacting support.

Error Response Format

{
  "success": false,
  "error": "Validation Error",
  "message": "Text must be between 10 and 5000 characters",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Common Status Codes

Code	Meaning
400	Validation error — check your request body
401	Missing or invalid authentication
403	Forbidden — insufficient permissions or role
404	Resource not found
429	Rate limit or monthly quota exceeded