← Back to Docs

API Reference

v1 API

Complete reference for every REST endpoint exposed by the GreenMetric AI platform.

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

Table of Contents

Authentication

Prefix: /v1/auth

Most endpoints are public. /v1/auth/me and /v1/auth/logout require a valid access token.

POST
/v1/auth/signup
// Request body
{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "Jane Doe"
}

// Response (200)
{
  "success": true,
  "data": {
    "user": { "id": "usr_...", "email": "user@example.com", "name": "Jane Doe" },
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci..."
  }
}
POST
/v1/auth/login
// Request body
{
  "email": "user@example.com",
  "password": "securePassword123"
}

// Response (200)
{
  "success": true,
  "data": {
    "user": { "id": "usr_...", "email": "user@example.com" },
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci..."
  }
}
POST
/v1/auth/refresh
POST
/v1/auth/logout
POST
/v1/auth/verify-email
POST
/v1/auth/forgot-password
POST
/v1/auth/reset-password
GET
/v1/auth/me

Analysis

Prefix: /v1/analysis

All endpoints require a valid API key (x-api-key header) or access token.

POST
/v1/analysis/text
// Request body
{
  "text": "Used iPhone 14 Pro Max, excellent condition, 256GB",  // 10–5,000 chars
  "destinationCountry": "US"  // optional, ISO 3166-1 alpha-2, defaults to "US"
}

// Supported countries: US, CN, IN, JP, KR, DE, GB, FR, IT, ES,
//                      SE, PT, VN, BD, TW, MX, TH, ID, TR, KH

// Response (202 Accepted)
{
  "success": true,
  "data": {
    "id": "analysis_abc123",
    "status": "pending",
    "type": "text",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}
POST
/v1/analysis/url
// Request body
{
  "url": "https://www.amazon.com/dp/B0CHX3QBCH",  // must be an Amazon URL
  "destinationCountry": "DE"  // optional, defaults to "US"
}

// Response (202 Accepted)
{
  "success": true,
  "data": {
    "id": "analysis_def456",
    "status": "pending",
    "type": "url",
    "createdAt": "2025-01-15T10:31:00Z"
  }
}
GET
/v1/analysis/:id
// Response (200) — when status is "completed"
{
  "success": true,
  "data": {
    "id": "analysis_abc123",
    "status": "completed",
    "product": {
      "name": "iPhone 14 Pro Max",
      "category": "Smartphones",
      "condition": "Excellent",
      "materials": ["Aluminum", "Glass", "Lithium-ion"],
      "originCountry": "CN"
    },
    "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": "High reuse value with minimal environmental cost",
      "estimatedSavings": "$580"
    },
    "recommendations": { ... },
    "comparison": { ... },
    "euGreenIndex": { ... }
  }
}
DELETE
/v1/analysis/:id
GET
/v1/analysis
// Query parameters
//   page    — Page number (default: 1)
//   limit   — Items per page (default: 20, max: 100)
//   status  — Filter: "pending" | "processing" | "completed" | "failed"
//   sort    — Sort field (default: "createdAt")
//   order   — "asc" | "desc" (default: "desc")

// Response (200)
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Organizations

Prefix: /v1/organizations

All endpoints require a valid access token. Some actions are restricted by member role.

POST
/v1/organizations
GET
/v1/organizations/:orgId
PATCH
/v1/organizations/:orgId
DELETE
/v1/organizations/:orgId
GET
/v1/organizations/:orgId/members
POST
/v1/organizations/:orgId/members
PATCH
/v1/organizations/:orgId/members/:memberId
DELETE
/v1/organizations/:orgId/members/:memberId

API Keys

Prefix: /v1/organizations/:orgId/api-keys

All endpoints require a valid access token with admin or owner role.

POST
/v1/organizations/:orgId/api-keys
// Request body
{
  "name": "Production Backend",
  "permissions": ["analysis:write", "analysis:read"],
  "restrictions": {
    "allowedIps": ["203.0.113.0/24"],  // optional IP allowlist
    "allowedOrigins": ["https://myapp.com"]  // optional CORS origins
  },
  "expiresIn": "90d"  // optional: "30d", "90d", "365d", or null (never)
}

// Response (201) — key is shown only once
{
  "success": true,
  "data": {
    "id": "key_...",
    "name": "Production Backend",
    "key": "gm_live_xxxxxxxxxxxxxxxxxxxx",
    "prefix": "gm_live_",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}
GET
/v1/organizations/:orgId/api-keys
GET
/v1/organizations/:orgId/api-keys/:keyId
PATCH
/v1/organizations/:orgId/api-keys/:keyId
DELETE
/v1/organizations/:orgId/api-keys/:keyId

Webhooks

Prefix: /v1/organizations/:orgId/webhooks

All endpoints require a valid access token with admin or owner role.

POST
/v1/organizations/:orgId/webhooks
// Request body
{
  "url": "https://myapp.com/webhooks/greenmetric",
  "events": [
    "analysis.completed",
    "analysis.failed",
    "quota.warning",
    "quota.exceeded"
  ],
  "secret": "whsec_..."  // optional, auto-generated if omitted
}

// Webhook payload example (analysis.completed)
{
  "event": "analysis.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "analysisId": "analysis_abc123",
    "status": "completed",
    "scores": { "overallScore": 87, "rating": "A+" }
  }
}
GET
/v1/organizations/:orgId/webhooks
GET
/v1/organizations/:orgId/webhooks/:webhookId
PATCH
/v1/organizations/:orgId/webhooks/:webhookId
DELETE
/v1/organizations/:orgId/webhooks/:webhookId
GET
/v1/organizations/:orgId/webhooks/:webhookId/deliveries

Billing

Prefix: /v1/billing

All endpoints require a valid access token. Organization-scoped via the token.

POST
/v1/billing/checkout
POST
/v1/billing/portal
GET
/v1/billing/subscription
// Response (200)
{
  "success": true,
  "data": {
    "plan": "pro",
    "status": "active",
    "currentPeriodEnd": "2025-02-15T00:00:00Z",
    "cancelAtPeriodEnd": false,
    "limits": {
      "monthlyApiCalls": 50000,
      "membersPerOrg": 25
    }
  }
}
GET
/v1/billing/invoices
GET
/v1/billing/usage
// Response (200)
{
  "success": true,
  "data": {
    "apiCallsThisPeriod": 1234,
    "limit": 50000,
    "periodStart": "2025-01-15T00:00:00Z",
    "periodEnd": "2025-02-15T00:00:00Z"
  }
}

Analytics

Prefix: /v1/analytics

All endpoints require a valid access token with admin or owner role.

GET
/v1/analytics/usage
GET
/v1/analytics/latency
GET
/v1/analytics/errors
GET
/v1/analytics/api-keys

Reports

Prefix: /v1/reports

All endpoints require a valid access token.

GET
/v1/reports/personal
GET
/v1/reports/personal/summary

Health

Prefix: /v1/health

No authentication required.

GET
/v1/health
// Response (200)
{
  "status": "ok",
  "timestamp": "2025-01-15T10:00:00Z",
  "uptime": 86400,
  "version": "0.1.0"
}