Check a domain for carbon.txt

Overview

CO2.js comes with a handy function which lets you check if a web domain hosts a valid carbon.txt file. Under the hood, this function uses the Greencheck API to return results. You can learn more about the carbon.txt project at https://carbontxt.org.

In this tutorial, you will install CO2.js in a Node environment. Then, you will check a domain to see if it hosts a valid carbon.txt file.

Before starting

You can follow along with this tutorial in your local development environment, or by using the button below to launch the project in Gitpod.

Local development

If you are following along this tutorial locally, you will need to have the following setup on your machine:

• Node version 14 or later
• NPM version 6 or later

Learning goals

• How to install CO2.js using NPM
• How to lookup if a domain hosts a carbon.txt file

Setting up

If you are following along using the Gitpod starter template, you can skip this section.

Otherwise, create a new folder locally called co2js-carbon-txt and navigate into that folder. Then, initialise NPM.

mkdir co2js-carbon-txt
cd co2js-carbon-txt
npm init -y

Next, create an check.js file, and open it in your code editor of choice. We will write the code for this tutorial inside the check.js file.

Installing CO2.js

Inside your project folder, run the following command to install CO2.js as a dependency.

npm install @tgwf/co2

Initialise CO2.js

In your project’s check.js file, add the following code to include the CO2.js carbon-txt module's check() function in your code.

const { check } = require("@tgwf/co2/carbon-txt");

Lookup a domain to find a carbon.txt file

To check if a single domain is green hosted, you can pass the following parameters into the check function:

Parameter	Type	Required	Description
domain	string	Required	the website domain you want to check for green hosting.
options	object	Required	An object of domain check options.

The options object may contain the following keys:

Key	Type	Required	Description
apiKey	string	Required	A valid Green Web Foundation API key. You can get one from the Green Web Portal.
verbose	boolean		indicate where you want to receive the full JSON payload from the API (including logs), or just the core data. Default: false
userAgentIdentifier	string		representing the app, site, or organisation that is making the request.
customValidator	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).

Adding the code below to the check.js file allows us to check if the domain google.com for a valid carbon.txt file and return the results of the parsed file if found.

const options = {
  apiKey: "my-api-key",
  verbose: false
};
check("google.com", options).then((result) => {
  console.log(result);
});

Running the code above returns the following result:

node check.js

# Output:
# {
#  success: false,
#  errors: [
#    'UnreachableCarbonTxtFile: Unable to find a valid carbon.txt file at the domain google.com'
#  ]
# }

If you want to get the full logs from the carbon.txt validator, you can change set verbose: true in the options.

Understanding the validator response.

The validator will return a JSON response with either success or failure results.

Success

{
  "success": true,
  "url": "https://example.com/carbon.txt",
  "data": {
    "version": "0.5",
    "last_updated": null,
    "upstream": null,
    "org": {
      "disclosures": [
        {
          "doc_type": "web-page",
          "url": "https://example.com",
          "domain": null,
          "valid_until": null,
          "title": null
        }
      ]
    }
  },
  "logs": [
    "Attempting to validate contents of version='0.5'\n[org]\ndisclosures=[{ doc_t",
    "Carbon.txt file parsed as valid TOML.",
    "Parsed TOML was recognised as valid Carbon.txt file with syntax version 0.5.\n",
    "ai-model-card_greenweb: Processing supporting document: https://example.com for None",
    "carbon_txt.process_ai_model_card: Document type web-page seen. Doing nothing",
    "csrd_greenweb: Processing supporting document: https://example.com for None",
    "carbon_txt.process_csrd_document: Document type web-page seen. Doing nothing",
    "ai-model-card_greenweb: Processing supporting document: https://example.com for None",
    "carbon_txt.process_ai_model_card: Document type web-page seen. Doing nothing",
    "csrd_greenweb: Processing supporting document: https://example.com for None",
    "carbon_txt.process_csrd_document: Document type web-page seen. Doing nothing"
  ],
  "document_data": {}
}

The object has the following fields:

• The success field returns true, indicating a carbon.txt file was found and succesfully parsed.
• A url field will be returned with the canonical url of the file found.
• The contents of the carbon.txt file, serialized as JSON, inside the data field.
• An array of logs which detail the carbon.txt lookup and validation process carried out, for debugging purposes.
• A document_data object, containing any data parsed from linked documents by installed carbon.txt plugins. Currently the API provides plugins to parse CSRD reports and AI model cards.
• If you requested a domain which delegates its carbon.txt file to another domain using a DNS TXT record or HTTP header, the delegation_method field will indicate the delegation method followed.

Failure

Below is an example of an error returned due to incorrect doc_type.

{
    "success": false,
    "errors": [
        {
            "type": "literal_error",
            "loc": [
                "org",
                "disclosures",
                0,
                "doc_type"
            ],
            "msg": "Input should be 'web-page', 'annual-report', 'sustainability-page', 'certificate', 'csrd-report', 'ai-model-card' or 'other'",
            "input": "report",
            "ctx": {
                "expected": "'web-page', 'annual-report', 'sustainability-page', 'certificate', 'csrd-report', 'ai-model-card' or 'other'"
            },
            "url": "https://errors.pydantic.dev/2.13/v/literal_error"
        }
    ],
    "logs": [
        "Attempting to validate contents of version=\"0.5\"\nlast_updated=2026-06-01\n\n[",
        "Carbon.txt file parsed as valid TOML.",
        "Validation failed.",
        "Validation error: 1 validation error for CarbonTxtFile\norg.disclosures.0.doc_type\n  Input should be 'web-page', 'annual-report', 'sustainability-page', 'certificate', 'csrd-report', 'ai-model-card' or 'other' [type=literal_error, input_value='report', input_type=str]\n    For further information visit https://errors.pydantic.dev/2.13/v/literal_error"
    ]
}

The object has the following fields:

• The success field returns false, indicating carbon.txt content was not succesfully parsed.
• The detials of errors found are serialized inside the errors array.
• An array of logs which detail the carbon.txt lookup and validation process carried out, for debugging purposes.