Add carbon.txt validator endpoint

[fershad]

Triage

Type of change

Please select any of the below items that are appropriate.

This pull request:

• Adds a new carbon estimation model to CO2.js
• Adds new functionality to an existing model
• Fixes a bug with an existing model implementation
• Add other new functionality to CO2.js
• Add new data to CO2.js
• Improves developer experience for contributors
• Adds contributors to CO2.js
• Does something not specified above

Related issue/s

Please list below any issues this pull request is related to.

• Add carbon.txt lookup endpoint #273

Docs changes required

Do any changes made in this pull request require parts of the CO2.js documentation to be updated?

• Yes
• No
• I don't know

If you answered "Yes", please create an corresponding issue in our Developer Documentation repository.

Describe the changes made in this pull request

As clearly as possible, describe the changes made in the pull request. You should at least detail "what changes have been made" and "what the results of these changes will be".

This change introduces the ability for developers to perform carbon.txt lookups against a domain. This functionality will work similar to the existing green hosting check functionality that exists in CO2.js. Developers will be able to submit a website domain, and will be returned any linked sustainability content that is contained in a carbon.txt file hosted on that domain.

import { check } from "@tgwf/co2/carbon-txt";

const test = async () => {
  const result = await check("example.com");
  console.log(result);
};

test();

The check() function accepts:

• domain: REQUIRED A string representing the domain that is being checked. The protocol (i.e. http://, https://) should be excluded.
• options: Optional An object that can contain:
  • verbose: A boolean indicate where you want to receive the full JSON payload from the API (including logs), or just the core data.
  • userAgentIdentifier: A string representing the app, site, or organisation that is making the request.
  • url: A string representing the URL of the carbon.txt validator endpoint (if you do not want to use the Green Web Foundation carbon.txt API endpoint)

Response

Results are returned with the success key indicating if the carbon.txt lookup was successful/not successful.

The following responses will be returned:

Success: verbose: true

const result = await check("example.com", { verbose: true });

{
      success: true,
      url: "https://example.com/carbon.txt",
      delegation_method: null,
      data: {
        version: "0.4",
        last_updated: "2026-03-09",
        upstream: {
          services: [
            {
              domain: "www.example.com",
              name: null,
              service_type: "cdn",
            },
          ],
        },
        org: {
          disclosures: [
            {
              doc_type: "web-page",
              url: "https://www.sampledoc.com/disclosure",
              domain: null,
              valid_until: null,
              title: "A sample disclosure",
            },
          ],
        },
      },
      document_data: {},
      logs: [
        "Attempting to resolve domain: example.com",
        "Trying a DNS delegated lookup for domain example.com",
        "Checking if a carbon.txt file is reachable at https://example.com/carbon.txt",
        "New Carbon text file found at: https://example.com/carbon.txt",
        "Carbon.txt file parsed as valid TOML.",
      ],
    };

Success: verbose: false

const result = await check("example.com");

{
        success: true,
        url: "https://example.com/carbon.txt",
        org: {
          disclosures: [
          {
            doc_type: "web-page",
            url: "https://www.sampledoc.com/disclosure",
            domain: null,
            valid_until: null,
            title: "A sample disclosure",
          },
        ],
        },
        upstream: 
           services: [
          {
            domain: "www.example.com",
            name: null,
            service_type: "cdn",
          },
        ],
        },
      }

Failed: verbose: true

const result = await check("nocarbontxt.com", { verbose: true });

{
      success: false,
      url: null,
      delegation_method: null,
      errors: [
        "NotParseableTOMLButHTML: Invalid statement (at line 1, column 1)",
      ],
      logs: [
        "Attempting to resolve domain: nocarbontxt.com",
        "Trying a DNS delegated lookup for domain nocarbontxt.com",
        "Checking if a carbon.txt file is reachable at https://example.com/carbon.txt",
        "New Carbon text file found at: https://example.com/carbon.txt",
        "TOML parsing failed.",
      ],
    };

Failed: verbose: false

const result = await check("nocarbontxt.com");

{
        success: false,
        errors: [
          "NotParseableTOMLButHTML: Invalid statement (at line 1, column 1)",
        ],
      }

Failed: Invalid domain

const result = await check("https://example.com");

{
        success: false,
        errors: ["Invalid domain format"],
}

[fershad]

@mrchrisadams not expecting a full review from you, but just want to get someone else's reckons on this implementation.

[fershad]

I’ve got working examples from in the browser hitting the carbon.txt validator endpoint with CO2.js.

CodePen: CO2.js 🤝🏼 Carbon.txt

Observable: https://observablehq.com/d/55ee768bb40c1f4b

So looks like CORS won’t be an issue.

[mrchrisadams]

Thanks for this @fershad - one nit pick about docstrings, and a couple of other bits that could be deferred, but would be nice to have added in this PR if possible