{
  "info": {
    "_postman_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "AlchemOS Positive API",
    "description": "Complete REST API collection for AlchemOS Positive — the ESG & Carbon Management platform.\n\n## Authentication\n\nMost endpoints require a Bearer JWT or an `X-API-Key` header.\n\n1. **JWT**: Obtain a token via `POST /api/identity/auth/login` then set it on the collection variable `jwt_token`.\n2. **API Key**: Create one in the Portal under Settings → API Keys, then set `api_key` on the collection variable.\n\n## Base URL\n\nUpdate the `base_url` collection variable to match your environment:\n- Local gateway: `http://localhost:8080`\n- Production: `https://api.alchemos.io`",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url", "value": "http://localhost:8080", "type": "string" },
    { "key": "jwt_token", "value": "", "type": "string" },
    { "key": "api_key", "value": "", "type": "string" }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{jwt_token}}", "type": "string" }]
  },
  "item": [
    {
      "name": "Public — Registration",
      "description": "Self-service tenant registration. All endpoints are unauthenticated.",
      "item": [
        {
          "name": "Register new tenant",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": { "raw": "{{base_url}}/api/public/registration", "host": ["{{base_url}}"], "path": ["api", "public", "registration"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"companyName\": \"Acme Corp\",\n  \"displayName\": \"acme\",\n  \"adminEmail\": \"admin@acme.com\",\n  \"password\": \"Str0ng!Pass#2026\",\n  \"fullName\": \"Jane Smith\",\n  \"jobTitle\": \"Sustainability Manager\",\n  \"planCode\": \"starter\",\n  \"recaptchaToken\": \"<recaptcha-v3-token>\"\n}"
            },
            "description": "Register a new tenant. Always returns 202 Accepted regardless of outcome (anti-enumeration). An email is sent to the admin address if registration succeeds."
          }
        },
        {
          "name": "Verify email token",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": { "raw": "{{base_url}}/api/public/registration/verify", "host": ["{{base_url}}"], "path": ["api", "public", "registration", "verify"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"token\": \"<verification-token-from-email>\"\n}"
            },
            "description": "Verify email ownership using the token from the verification email. Token is single-use and expires after 1 hour."
          }
        },
        {
          "name": "Check company name availability",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/public/registration/check-name?name=Acme Corp",
              "host": ["{{base_url}}"],
              "path": ["api", "public", "registration", "check-name"],
              "query": [{ "key": "name", "value": "Acme Corp" }]
            },
            "description": "Check if a company/tenant name is available. Always returns HTTP 200 with `{ \"available\": true|false }` — never 404 or 409 (anti-enumeration)."
          }
        },
        {
          "name": "Resend verification email",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": { "raw": "{{base_url}}/api/public/registration/resend", "host": ["{{base_url}}"], "path": ["api", "public", "registration", "resend"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"admin@acme.com\"\n}"
            },
            "description": "Resend the verification email. Rate-limited to 3 attempts per email address per hour."
          }
        }
      ]
    },
    {
      "name": "Public — CMS",
      "description": "Public content endpoints. No authentication required.",
      "item": [
        {
          "name": "List published blog posts",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/public/cms/blog-posts?page=1&pageSize=10",
              "host": ["{{base_url}}"],
              "path": ["api", "public", "cms", "blog-posts"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "pageSize", "value": "10" },
                { "key": "tag", "value": "", "disabled": true }
              ]
            },
            "description": "Returns paginated published blog posts. Filter by tag using the `tag` query parameter."
          }
        },
        {
          "name": "Get blog post by slug",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/public/cms/blog-posts/:slug",
              "host": ["{{base_url}}"],
              "path": ["api", "public", "cms", "blog-posts", ":slug"],
              "variable": [{ "key": "slug", "value": "scope-3-emissions-guide" }]
            },
            "description": "Returns a single published blog post by its URL slug. Returns 404 for drafts or non-existent slugs."
          }
        },
        {
          "name": "Get page content section",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/public/cms/page-content/:key",
              "host": ["{{base_url}}"],
              "path": ["api", "public", "cms", "page-content", ":key"],
              "variable": [{ "key": "key", "value": "landing-hero" }]
            },
            "description": "Returns a CMS page content section by key. Keys: `landing-hero`, `stats-bar`, `testimonials`."
          }
        },
        {
          "name": "Submit demo / contact lead",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": { "raw": "{{base_url}}/api/public/cms/leads", "host": ["{{base_url}}"], "path": ["api", "public", "cms", "leads"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"type\": \"DemoRequest\",\n  \"companyName\": \"Acme Corp\",\n  \"email\": \"jane@acme.com\",\n  \"fullName\": \"Jane Smith\",\n  \"jobTitle\": \"Sustainability Manager\",\n  \"message\": \"Interested in the Professional plan for 200 employees.\"\n}"
            },
            "description": "Submit a demo request or contact form lead. Triggers a confirmation email to the requester and a lead notification to the sales team."
          }
        }
      ]
    },
    {
      "name": "Carbon — Emissions",
      "description": "Carbon tracking and emission entry endpoints. Requires authentication.",
      "item": [
        {
          "name": "List emission entries",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": {
              "raw": "{{base_url}}/api/carbon/emissions?page=1&pageSize=20",
              "host": ["{{base_url}}"],
              "path": ["api", "carbon", "emissions"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "pageSize", "value": "20" },
                { "key": "scope", "value": "", "disabled": true },
                { "key": "from", "value": "", "disabled": true },
                { "key": "to", "value": "", "disabled": true }
              ]
            },
            "description": "Returns paginated Scope 1/2/3 emission entries for the authenticated tenant."
          }
        },
        {
          "name": "Create emission entry",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/carbon/emissions", "host": ["{{base_url}}"], "path": ["api", "carbon", "emissions"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"scope\": 1,\n  \"category\": \"Stationary Combustion\",\n  \"activityData\": 1000,\n  \"unit\": \"kWh\",\n  \"emissionFactor\": 0.233,\n  \"date\": \"2026-01-15\",\n  \"notes\": \"Office electricity — January 2026\"\n}"
            },
            "description": "Record a new emission entry. CO₂e is calculated server-side using the provided emission factor."
          }
        },
        {
          "name": "Get climate score",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": { "raw": "{{base_url}}/api/carbon/climate-score", "host": ["{{base_url}}"], "path": ["api", "carbon", "climate-score"] },
            "description": "Returns the current climate performance score for the tenant based on emission trends and offset activity."
          }
        },
        {
          "name": "Travel carbon calculator",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/carbon/travel-carbon", "host": ["{{base_url}}"], "path": ["api", "carbon", "travel-carbon"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"mode\": \"flight\",\n  \"distanceKm\": 1200,\n  \"passengers\": 2,\n  \"class\": \"economy\"\n}"
            },
            "description": "Calculate CO₂e for a travel activity. Supports flight, car, rail, and ferry modes."
          }
        }
      ]
    },
    {
      "name": "Offset Marketplace",
      "description": "Browse, purchase and retire carbon offsets. Requires authentication.",
      "item": [
        {
          "name": "List offset projects",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": {
              "raw": "{{base_url}}/api/offsets/projects?page=1&pageSize=10",
              "host": ["{{base_url}}"],
              "path": ["api", "offsets", "projects"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "pageSize", "value": "10" },
                { "key": "standard", "value": "", "disabled": true },
                { "key": "type", "value": "", "disabled": true }
              ]
            },
            "description": "Lists available carbon offset projects. Filter by verification standard (e.g., `VCS`, `Gold Standard`) or project type."
          }
        },
        {
          "name": "Purchase offsets",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/offsets/purchase", "host": ["{{base_url}}"], "path": ["api", "offsets", "purchase"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"projectId\": \"<project-uuid>\",\n  \"tonnes\": 10,\n  \"notes\": \"Q1 2026 offset purchase\"\n}"
            },
            "description": "Purchase carbon offset credits from a verified project."
          }
        },
        {
          "name": "Retire offsets",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/offsets/retire", "host": ["{{base_url}}"], "path": ["api", "offsets", "retire"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"purchaseId\": \"<purchase-uuid>\",\n  \"tonnes\": 10,\n  \"retirementReason\": \"Annual net-zero commitment 2026\"\n}"
            },
            "description": "Retire purchased offset credits. Retired credits are permanently removed from circulation and a certificate is generated."
          }
        },
        {
          "name": "List order history",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": { "raw": "{{base_url}}/api/offsets/orders", "host": ["{{base_url}}"], "path": ["api", "offsets", "orders"] },
            "description": "Returns the offset purchase and retirement history for the tenant."
          }
        }
      ]
    },
    {
      "name": "Sustainability Reporting",
      "description": "Generate and export compliance reports. Requires authentication.",
      "item": [
        {
          "name": "List reports",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": { "raw": "{{base_url}}/api/reporting/reports", "host": ["{{base_url}}"], "path": ["api", "reporting", "reports"] }
          }
        },
        {
          "name": "Generate report",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/reporting/reports", "host": ["{{base_url}}"], "path": ["api", "reporting", "reports"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"type\": \"GHGInventory\",\n  \"periodFrom\": \"2026-01-01\",\n  \"periodTo\": \"2026-03-31\",\n  \"format\": \"PDF\"\n}"
            },
            "description": "Generates a new compliance report. The report is processed asynchronously; poll the report ID for status."
          }
        },
        {
          "name": "Export report (PDF / CSV)",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": {
              "raw": "{{base_url}}/api/reporting/reports/:reportId/export?format=PDF",
              "host": ["{{base_url}}"],
              "path": ["api", "reporting", "reports", ":reportId", "export"],
              "variable": [{ "key": "reportId", "value": "<report-uuid>" }],
              "query": [{ "key": "format", "value": "PDF" }]
            },
            "description": "Downloads the generated report as PDF or CSV."
          }
        }
      ]
    },
    {
      "name": "Sustainability Certificates",
      "description": "Request, approve and verify sustainability certificates.",
      "item": [
        {
          "name": "Request certificate",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/certificates/requests", "host": ["{{base_url}}"], "path": ["api", "certificates", "requests"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"type\": \"CarbonNeutral\",\n  \"periodFrom\": \"2025-01-01\",\n  \"periodTo\": \"2025-12-31\",\n  \"notes\": \"Annual 2025 carbon neutral claim\"\n}"
            }
          }
        },
        {
          "name": "Verify certificate (public)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/certificates/verify/:code",
              "host": ["{{base_url}}"],
              "path": ["api", "certificates", "verify", ":code"],
              "variable": [{ "key": "code", "value": "<certificate-code>" }]
            },
            "description": "Public endpoint. Validates a certificate QR code. No authentication required."
          }
        }
      ]
    },
    {
      "name": "Sustainability Targets",
      "description": "Set and track net-zero targets and milestones.",
      "item": [
        {
          "name": "List targets",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": { "raw": "{{base_url}}/api/targets", "host": ["{{base_url}}"], "path": ["api", "targets"] }
          }
        },
        {
          "name": "Create target",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{api_key}}" }
            ],
            "url": { "raw": "{{base_url}}/api/targets", "host": ["{{base_url}}"], "path": ["api", "targets"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Net Zero by 2030\",\n  \"targetType\": \"NetZero\",\n  \"baselineYear\": 2024,\n  \"targetYear\": 2030,\n  \"reductionPercent\": 100\n}"
            }
          }
        },
        {
          "name": "List milestones",
          "request": {
            "method": "GET",
            "header": [{ "key": "X-API-Key", "value": "{{api_key}}" }],
            "url": {
              "raw": "{{base_url}}/api/targets/:targetId/milestones",
              "host": ["{{base_url}}"],
              "path": ["api", "targets", ":targetId", "milestones"],
              "variable": [{ "key": "targetId", "value": "<target-uuid>" }]
            }
          }
        }
      ]
    },
    {
      "name": "Developer — API Keys & Webhooks",
      "description": "Manage programmatic API access. Requires authentication.",
      "item": [
        {
          "name": "List API keys",
          "request": {
            "method": "GET",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": { "raw": "{{base_url}}/api/developer/api-keys", "host": ["{{base_url}}"], "path": ["api", "developer", "api-keys"] }
          }
        },
        {
          "name": "Create API key",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Authorization", "value": "Bearer {{jwt_token}}" }
            ],
            "url": { "raw": "{{base_url}}/api/developer/api-keys", "host": ["{{base_url}}"], "path": ["api", "developer", "api-keys"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"CI Pipeline Key\",\n  \"scopes\": [\"carbon:read\", \"reporting:read\"],\n  \"expiresInDays\": 365\n}"
            },
            "description": "Creates a new API key. The raw key value is only returned once — store it securely."
          }
        },
        {
          "name": "Revoke API key",
          "request": {
            "method": "DELETE",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": {
              "raw": "{{base_url}}/api/developer/api-keys/:keyId",
              "host": ["{{base_url}}"],
              "path": ["api", "developer", "api-keys", ":keyId"],
              "variable": [{ "key": "keyId", "value": "<key-uuid>" }]
            }
          }
        },
        {
          "name": "List webhooks",
          "request": {
            "method": "GET",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": { "raw": "{{base_url}}/api/developer/webhooks", "host": ["{{base_url}}"], "path": ["api", "developer", "webhooks"] }
          }
        },
        {
          "name": "Register webhook",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Authorization", "value": "Bearer {{jwt_token}}" }
            ],
            "url": { "raw": "{{base_url}}/api/developer/webhooks", "host": ["{{base_url}}"], "path": ["api", "developer", "webhooks"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://your-app.example.com/hooks/alchemos\",\n  \"events\": [\"emission.created\", \"offset.retired\", \"certificate.issued\"],\n  \"secret\": \"<hmac-signing-secret>\"\n}"
            },
            "description": "Register a webhook endpoint. Events are signed with HMAC-SHA256 using the provided secret. Verify the `X-AlchemOS-Signature` header on delivery."
          }
        }
      ]
    },
    {
      "name": "Admin CMS",
      "description": "Admin-only CMS management. Requires admin JWT with AdminOnly policy.",
      "item": [
        {
          "name": "List all blog posts (admin)",
          "request": {
            "method": "GET",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": { "raw": "{{base_url}}/api/identity/cms/blog-posts", "host": ["{{base_url}}"], "path": ["api", "identity", "cms", "blog-posts"] },
            "description": "Returns all posts including drafts. Admin only."
          }
        },
        {
          "name": "Create blog post (admin)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Authorization", "value": "Bearer {{jwt_token}}" }
            ],
            "url": { "raw": "{{base_url}}/api/identity/cms/blog-posts", "host": ["{{base_url}}"], "path": ["api", "identity", "cms", "blog-posts"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"title\": \"Understanding Scope 3 Emissions\",\n  \"slug\": \"understanding-scope-3-emissions\",\n  \"excerpt\": \"A practical guide to measuring value chain emissions.\",\n  \"contentMarkdown\": \"## Introduction\\n\\nScope 3 emissions account for...\",\n  \"authorName\": \"AlchemOS Team\",\n  \"tags\": [\"scope-3\", \"csrd\", \"guide\"],\n  \"status\": \"Draft\",\n  \"metaTitle\": \"Understanding Scope 3 Emissions — AlchemOS\",\n  \"metaDescription\": \"A practical guide to measuring and reporting value chain Scope 3 emissions under CSRD and GHG Protocol.\"\n}"
            }
          }
        },
        {
          "name": "Update blog post (admin)",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Authorization", "value": "Bearer {{jwt_token}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/identity/cms/blog-posts/:id",
              "host": ["{{base_url}}"],
              "path": ["api", "identity", "cms", "blog-posts", ":id"],
              "variable": [{ "key": "id", "value": "<post-uuid>" }]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"title\": \"Understanding Scope 3 Emissions (Updated)\",\n  \"status\": \"Published\"\n}"
            }
          }
        },
        {
          "name": "Delete blog post (admin)",
          "request": {
            "method": "DELETE",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": {
              "raw": "{{base_url}}/api/identity/cms/blog-posts/:id",
              "host": ["{{base_url}}"],
              "path": ["api", "identity", "cms", "blog-posts", ":id"],
              "variable": [{ "key": "id", "value": "<post-uuid>" }]
            }
          }
        },
        {
          "name": "Get page content section (admin)",
          "request": {
            "method": "GET",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": {
              "raw": "{{base_url}}/api/identity/cms/page-content/:key",
              "host": ["{{base_url}}"],
              "path": ["api", "identity", "cms", "page-content", ":key"],
              "variable": [{ "key": "key", "value": "landing-hero" }]
            }
          }
        },
        {
          "name": "Update page content section (admin)",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Authorization", "value": "Bearer {{jwt_token}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/identity/cms/page-content/:key",
              "host": ["{{base_url}}"],
              "path": ["api", "identity", "cms", "page-content", ":key"],
              "variable": [{ "key": "key", "value": "landing-hero" }]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sectionTitle\": \"Hero\",\n  \"headline\": \"Measure, manage and offset your carbon footprint\",\n  \"subtext\": \"From first entry to verified certificate.\",\n  \"jsonData\": null\n}"
            }
          }
        },
        {
          "name": "List leads (admin)",
          "request": {
            "method": "GET",
            "header": [{ "key": "Authorization", "value": "Bearer {{jwt_token}}" }],
            "url": {
              "raw": "{{base_url}}/api/identity/cms/leads?status=New",
              "host": ["{{base_url}}"],
              "path": ["api", "identity", "cms", "leads"],
              "query": [{ "key": "status", "value": "New", "disabled": true }]
            }
          }
        },
        {
          "name": "Update lead status (admin)",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Authorization", "value": "Bearer {{jwt_token}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/identity/cms/leads/:id",
              "host": ["{{base_url}}"],
              "path": ["api", "identity", "cms", "leads", ":id"],
              "variable": [{ "key": "id", "value": "<lead-uuid>" }]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"status\": \"DemoScheduled\",\n  \"notes\": \"Demo booked for 2026-04-10 at 14:00 UTC\"\n}"
            }
          }
        }
      ]
    }
  ]
}