Validating carbon.txt URL

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

Endpoint

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

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 url parameter.

JavaScript
cURL

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

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

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.

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" ] }