Validating carbon.txt URL

To validate a carbon.txt file by hosted at a public domain, make a POST request to the /api/validate/domain endpoint, passing a JSON-encoded body with the carbon.txt file contents encoded as the domain parameter.

Endpoint

A POST request should be sent to https://carbon-txt-api.greenweb.org/api/validate/domain.

Authentication

The request header should include x-api-key: my-api-key, where my-api-key is your Green Web Foundation API key. Learn more about API authentication.

Payload

The request should include a JSON-encoded body with the carbon.txt file contents encoded as the domain parameter.

fetch("https://carbon-txt-api.greenweb.org/api/validate/domain", {
  method: "POST",
  headers: {
    "X-Api-Key": gwf_xxxxxxx.xxxxxxxxxxxxxxxxx,
  },
  body: JSON.stringify({ domain: example.com })
})

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \
    --data "{\"domain\": \"example.com/\"  }" \
    https://carbon-txt-api.greenweb.org/api/validate/domain

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.