From f23ee15041510f74d1d5614129c730779c7e3b7a Mon Sep 17 00:00:00 2001 From: Tim Cowlishaw Date: Wed, 27 May 2026 19:49:20 +0200 Subject: [PATCH 01/13] Add documentation for carbon.txt HTTP API --- src/docs/api/carbon-txt/carbon-txt.json | 12 +++ src/docs/api/carbon-txt/overview.md | 125 ++++++++++++++++++++++++ src/docs/carbon-txt/overview.md | 17 +++- 3 files changed, 151 insertions(+), 3 deletions(-) create mode 100644 src/docs/api/carbon-txt/carbon-txt.json create mode 100644 src/docs/api/carbon-txt/overview.md diff --git a/src/docs/api/carbon-txt/carbon-txt.json b/src/docs/api/carbon-txt/carbon-txt.json new file mode 100644 index 0000000..b4e764d --- /dev/null +++ b/src/docs/api/carbon-txt/carbon-txt.json @@ -0,0 +1,12 @@ + +{ + "tags": [ + "carbon-txt" + ], + "name": "Carbon.txt validation API", + "permalink": "{% if not overridePermalink %}{% generateDocsPath page.filePathStem %}/index.html{% else %}{{ overridePermalink }}{% endif %}", + "layout": "layouts/doc.njk", + "repoVersion": "1", + "repo": "carbon-txt-validator", + "repository": "https://github.com/thegreenwebfoundation/carbon.-txt-validatorl" +} diff --git a/src/docs/api/carbon-txt/overview.md b/src/docs/api/carbon-txt/overview.md new file mode 100644 index 0000000..1072f7b --- /dev/null +++ b/src/docs/api/carbon-txt/overview.md @@ -0,0 +1,125 @@ +--- +tags: apiMain +libraryName: Carbon.txt validation API +title: Overview +description: Use this API to lookup and validate carbon.txt files. +hasTabs: true +eleventyNavigation: + key: carbon-txt-api-overview + title: Overview + order: 1 +--- + +# Carbon.txt validation API + +The carbon.txt validation API allows you to validate the syntax and content of carbon.txt files, and to look up the carbon.txt file for a given domain. + +# Authentication + +To use the carbon.txt validation API, you will need to authenticate using a Green Web Foundation API key, available by logging into the [Green Web Portal](https://admin.thegreenwebfoundation.org). Register or log into an existing account, then navigate to the API keys section in the main navigation - ou will be asked to provide some information on your planned use case, and to accept our privacy policy before creating your first key. You may create up to a maximum of 3 API keys by default. + +Once you have created a key, you can use it to authenticate your requests to the carbon.txt validation API by passing the `X-Api-Key` header with your requests. By default, requests are rate limited to 2 per second per API key. + +If you need more keys, or a raised rate limit, please get in touch with our support team and we'll be happy to help. + + +[Interactive OpenAPI documentation](https://carbon-txt-api.greenweb.org/api/docs) for the API is also available, and has full details of all request and response parameters. + +# Usage + +The carbon.txt validation API allows carbon.txt files to be validated by direct upload, provided at a specific URL, or a fully qualified domain name. + +All carbon.txt validation endpoints are available from the [carbon-txt-api.greenweb.org](https://carbon-txt-api.greenweb.org) domain. + +## Validating a carbon.txt file by direct upload + +To validate a carbon.txt file by uploading contents directly, make a POST request to the `/api/validate/file` endpoint, passing a JSON-encoded body with the carbon.txt file contents encoded as the `text_contents` parameter. An example with CURL: + + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ + --data "{\"text_contents\": \"version='0.5'\n[org]\ndisclosures=[{ doc_type='web-page', url='https://example.com'}]\" }" \ + https://carbon-txt-api.greenweb.org/api/validate/file +``` + +## Validating a carbon.txt file by url + +To validate a carbon.txt file already available at a public URL, make a POST request to the `/api/validate/url` endpoint, passing a JSON-encoded body with the carbon.txt file url passed as the `url` parameter. An example with CURL: + + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ + --data "{\"url\": \"https://thegreenwebfoundation.org/carbon.txt\" }" \ + https://carbon-txt-api.greenweb.org/api/validate/url +``` + +## Looking up the carbon.txt file for a domain + +To look up and validate the carbon.txt file for a given domain, make a POST request to the `/api/validate/domain` endpoint, passing a JSON-encoded body with the fully-qualified domain name passed as the `domain` parameter. + + +This method will search for a carbon.txt at both the paths `/carbon.txt` and `/.well-known/carbon.txt`, and will follow any [delegation rules](https://carbontxt.org/faq) set up in DNS TXT records or HTTP headers on the queried domain. + +An example with CURL: + + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ + --data "{\"domain\": \"developers.thegreenwebfoundation.org\" }" \ + https://carbon-txt-api.greenweb.org/api/validate/domain +``` + +## Understanding the validator response. + +All three methods of validating a carbon.txt file return a response in the same format - a JSON object such as the following: + +```json +{ + "success": true, + "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 a boolean indicating whether or not a carbon.txt file was succesfully found and parsed. + - The contents of the carbon txt file, serialized as JSON, inside the `data` field, if the validation was succesful. + - 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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/model-cards). + - If you validated a url or domain, a `url` field will be returned with the canonical url of the file found. + - 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. + diff --git a/src/docs/carbon-txt/overview.md b/src/docs/carbon-txt/overview.md index fbb71d7..2aa38ec 100644 --- a/src/docs/carbon-txt/overview.md +++ b/src/docs/carbon-txt/overview.md @@ -76,10 +76,21 @@ Below are a collection of tools that you can use to get started creating a carbo -
  • +
  • -

    Syntax reference

    - Learn about all the details of the carbon.txt format from our syntax specification. +

    Validation API

    + Use our HTTP API to look up and validate carbon.txt files. +
    + Go to the documentation +
    +
    +
    • +
  • +
    +
    +

    Syntax reference

    + Learn about all the details of the carbon.txt format from our syntax specification. +
    Go to the reference
    From 0e7b924f4741e8f3007c1263e460e80c542c1522 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 11:02:39 +0800 Subject: [PATCH 02/13] validator api --- src/docs/api/carbon-txt/carbon-txt.json | 17 +++++++---------- src/docs/api/carbon-txt/overview.md | 7 +++---- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/src/docs/api/carbon-txt/carbon-txt.json b/src/docs/api/carbon-txt/carbon-txt.json index b4e764d..4412abf 100644 --- a/src/docs/api/carbon-txt/carbon-txt.json +++ b/src/docs/api/carbon-txt/carbon-txt.json @@ -1,12 +1,9 @@ - { - "tags": [ - "carbon-txt" - ], - "name": "Carbon.txt validation API", - "permalink": "{% if not overridePermalink %}{% generateDocsPath page.filePathStem %}/index.html{% else %}{{ overridePermalink }}{% endif %}", - "layout": "layouts/doc.njk", - "repoVersion": "1", - "repo": "carbon-txt-validator", - "repository": "https://github.com/thegreenwebfoundation/carbon.-txt-validatorl" + "tags": ["carbon-txt"], + "name": "Carbon.txt validator API", + "permalink": "{% if not overridePermalink %}{% generateDocsPath page.filePathStem %}/index.html{% else %}{{ overridePermalink }}{% endif %}", + "layout": "layouts/doc.njk", + "repoVersion": "1", + "repo": "carbon-txt-validator", + "repository": "https://github.com/thegreenwebfoundation/carbon.-txt-validator" } diff --git a/src/docs/api/carbon-txt/overview.md b/src/docs/api/carbon-txt/overview.md index 1072f7b..6815de5 100644 --- a/src/docs/api/carbon-txt/overview.md +++ b/src/docs/api/carbon-txt/overview.md @@ -1,6 +1,6 @@ --- tags: apiMain -libraryName: Carbon.txt validation API +libraryName: Carbon.txt validator API title: Overview description: Use this API to lookup and validate carbon.txt files. hasTabs: true @@ -10,9 +10,9 @@ eleventyNavigation: order: 1 --- -# Carbon.txt validation API +# Carbon.txt validator API -The carbon.txt validation API allows you to validate the syntax and content of carbon.txt files, and to look up the carbon.txt file for a given domain. +The carbon.txt validator API allows you to validate the syntax and content of carbon.txt files, and to look up the carbon.txt file for a given domain. # Authentication @@ -122,4 +122,3 @@ The object has the following fields: - A `document_data` object, containing any data parsed from linked documents by installed [carbon.txt plugins](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/model-cards). - If you validated a url or domain, a `url` field will be returned with the canonical url of the file found. - 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. - From 769d0d99d312d841e223dcb3a2107caf54d75c45 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 11:37:29 +0800 Subject: [PATCH 03/13] auth page --- src/docs/api/carbon-txt/authentication.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 src/docs/api/carbon-txt/authentication.md diff --git a/src/docs/api/carbon-txt/authentication.md b/src/docs/api/carbon-txt/authentication.md new file mode 100644 index 0000000..8e333ec --- /dev/null +++ b/src/docs/api/carbon-txt/authentication.md @@ -0,0 +1,20 @@ +--- +libraryName: Carbon.txt validator API +title: Authentication +description: Use this API to lookup and validate carbon.txt files. +hasTabs: true +eleventyNavigation: + key: carbon-txt-api-auth + title: Authentication + order: 2 +--- + +# Authentication + +To use the carbon.txt validator API, you will need to authenticate using a Green Web Foundation API key, available by logging into the [Green Web Portal](https://admin.thegreenwebfoundation.org). Register or log into an existing account, then navigate to the API keys section in the main navigation - ou will be asked to provide some information on your planned use case, and to accept our privacy policy before creating your first key. You may create up to a maximum of 3 API keys by default. + +Once you have created a key, you can use it to authenticate your requests to the carbon.txt validation API by passing the `X-Api-Key` header with your requests. By default, requests are rate limited to 2 per second per API key. + +If you need more keys, or a raised rate limit, please get in touch with our support team and we'll be happy to help. + +[Interactive OpenAPI documentation](https://carbon-txt-api.greenweb.org/api/docs) for the API is also available, and has full details of all request and response parameters. From d049fd2ae70ee0bb8d838158fac12653c8f7264c Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 11:37:36 +0800 Subject: [PATCH 04/13] check by content page --- src/docs/api/carbon-txt/check-by-content.md | 119 ++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 src/docs/api/carbon-txt/check-by-content.md diff --git a/src/docs/api/carbon-txt/check-by-content.md b/src/docs/api/carbon-txt/check-by-content.md new file mode 100644 index 0000000..5a8635e --- /dev/null +++ b/src/docs/api/carbon-txt/check-by-content.md @@ -0,0 +1,119 @@ +--- +libraryName: Carbon.txt validator API +title: Check by file content +description: Use this API to validate the contents of a carbon.txt file. +hasTabs: true +eleventyNavigation: + key: carbon-txt-api-check-by-content + title: Check by file content + order: 5 +--- + +# Validating carbon.txt file content + +To validate a carbon.txt file by uploading contents directly, make a `POST` request to the `/api/validate/file` endpoint, passing a JSON-encoded body with the carbon.txt file contents encoded as the `text_contents` parameter. + +{% set endpoint = 'file' %} +{% include 'partials/carbon-txt-endpoint.njk' %} + +## Payload + +The request should include a JSON-encoded body with the carbon.txt file contents encoded as the `text_contents` parameter. + +An example with CURL: + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ + --data "{\"text_contents\": \"version='0.5'\n[org]\ndisclosures=[{ doc_type='web-page', url='https://example.com'}]\" }" \ + https://carbon-txt-api.greenweb.org/api/validate/file +``` + +## Understanding the validator response. + +The validator will return a JSON response with either success or failure results. + +### Success + +```json +{ + "success": true, + "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 carbon.txt content was succesfully parsed. + - 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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/model-cards). + + + +### Failure + +Below is an example of an error returned due to incorrect `doc_type`. + +```json +{ + "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. From 6ea3a7727d9fec7d59de492f89f3d5799d3ea831 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 11:38:11 +0800 Subject: [PATCH 05/13] partial for endpoint and auth --- src/_includes/partials/carbon-txt-endpoint.njk | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 src/_includes/partials/carbon-txt-endpoint.njk diff --git a/src/_includes/partials/carbon-txt-endpoint.njk b/src/_includes/partials/carbon-txt-endpoint.njk new file mode 100644 index 0000000..48b40d2 --- /dev/null +++ b/src/_includes/partials/carbon-txt-endpoint.njk @@ -0,0 +1,7 @@ +## Endpoint + +A `POST` request should be sent to `https://carbon-txt-api.greenweb.org/api/validate/{{endpoint}}`. + +## 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](/api/carbon-txt/authentication). From 9793886d4fb1f0f21029af575d8825324a22a839 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:52:48 +0800 Subject: [PATCH 06/13] small text changes --- src/docs/api/carbon-txt/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/api/carbon-txt/authentication.md b/src/docs/api/carbon-txt/authentication.md index 8e333ec..21c1664 100644 --- a/src/docs/api/carbon-txt/authentication.md +++ b/src/docs/api/carbon-txt/authentication.md @@ -11,7 +11,7 @@ eleventyNavigation: # Authentication -To use the carbon.txt validator API, you will need to authenticate using a Green Web Foundation API key, available by logging into the [Green Web Portal](https://admin.thegreenwebfoundation.org). Register or log into an existing account, then navigate to the API keys section in the main navigation - ou will be asked to provide some information on your planned use case, and to accept our privacy policy before creating your first key. You may create up to a maximum of 3 API keys by default. +To use the carbon.txt validator API, you will need to authenticate using a Green Web Foundation API key, available by logging into the [Green Web Portal](https://admin.thegreenwebfoundation.org). Register or log into an existing account, then navigate to the API keys section in the main navigation - you will be asked to provide some information on your planned use case, and to accept our privacy policy before creating your first key. You may create a maximum of 3 API keys by default. Once you have created a key, you can use it to authenticate your requests to the carbon.txt validation API by passing the `X-Api-Key` header with your requests. By default, requests are rate limited to 2 per second per API key. From 27ceb15290860c4faa4ae55b7c792fd9c3bb4f57 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:53:18 +0800 Subject: [PATCH 07/13] create partial for results --- src/_includes/partials/carbon-txt-results.njk | 46 +++++++++++++++++ src/docs/api/carbon-txt/check-by-content.md | 49 ++----------------- 2 files changed, 50 insertions(+), 45 deletions(-) create mode 100644 src/_includes/partials/carbon-txt-results.njk diff --git a/src/_includes/partials/carbon-txt-results.njk b/src/_includes/partials/carbon-txt-results.njk new file mode 100644 index 0000000..f491c35 --- /dev/null +++ b/src/_includes/partials/carbon-txt-results.njk @@ -0,0 +1,46 @@ +## Understanding the validator response. + +The validator will return a JSON response with either success or failure results. + +### Success + +{{ successCodeBlock | safe}} + + +### Failure + +Below is an example of an error returned due to incorrect `doc_type`. + +```json +{ + "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. diff --git a/src/docs/api/carbon-txt/check-by-content.md b/src/docs/api/carbon-txt/check-by-content.md index 5a8635e..30a1f0b 100644 --- a/src/docs/api/carbon-txt/check-by-content.md +++ b/src/docs/api/carbon-txt/check-by-content.md @@ -30,12 +30,7 @@ curl -X POST \ https://carbon-txt-api.greenweb.org/api/validate/file ``` -## Understanding the validator response. - -The validator will return a JSON response with either success or failure results. - -### Success - +{% set successCodeBlock %} ```json { "success": true, @@ -72,48 +67,12 @@ The validator will return a JSON response with either success or failure results } ``` + The object has the following fields: - The `success` field returns `true`, indicating carbon.txt content was succesfully parsed. - 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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/model-cards). +{% endset %} - - -### Failure - -Below is an example of an error returned due to incorrect `doc_type`. - -```json -{ - "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. +{% include 'partials/carbon-txt-results.njk' %} From 074a30c0f8f9998a6d4e5b9a09f1ec44a13626e1 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:53:34 +0800 Subject: [PATCH 08/13] check by domain and url --- src/docs/api/carbon-txt/check-by-domain.md | 91 ++++++++++++++++++++++ src/docs/api/carbon-txt/check-by-url.md | 89 +++++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 src/docs/api/carbon-txt/check-by-domain.md create mode 100644 src/docs/api/carbon-txt/check-by-url.md diff --git a/src/docs/api/carbon-txt/check-by-domain.md b/src/docs/api/carbon-txt/check-by-domain.md new file mode 100644 index 0000000..07bc123 --- /dev/null +++ b/src/docs/api/carbon-txt/check-by-domain.md @@ -0,0 +1,91 @@ +--- +libraryName: Carbon.txt validator API +title: Check by website domain +description: Use this API to validate the contents of a carbon.txt file hosted at a website domain. +hasTabs: true +eleventyNavigation: + key: carbon-txt-api-check-by-domain + title: Check by website domain + order: 4 +--- + +# 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. + +{% set endpoint = 'domain' %} +{% include 'partials/carbon-txt-endpoint.njk' %} + +## Payload + +The request should include a JSON-encoded body with the carbon.txt file contents encoded as the `domain` parameter. + +An example with CURL: + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ + --data "{\"domain\": \"https://example.com/carbon.txt\" }" \ + https://carbon-txt-api.greenweb.org/api/validate/domain +``` + +
    +
    +
    +

    Important

    +

    Please note that the carbon.txt validator does not follow redirects. It will return a failure result if it encounters a redirect, and will flag this error in the logs.

    +
    +
    +
    + + +{% set successCodeBlock %} +```json +{ + "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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/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. +{% endset %} + +{% include 'partials/carbon-txt-results.njk' %} diff --git a/src/docs/api/carbon-txt/check-by-url.md b/src/docs/api/carbon-txt/check-by-url.md new file mode 100644 index 0000000..f266f96 --- /dev/null +++ b/src/docs/api/carbon-txt/check-by-url.md @@ -0,0 +1,89 @@ +--- +libraryName: Carbon.txt validator API +title: Check by carbon.txt URL +description: Use this API to validate the contents of a carbon.txt file hosted at a fixed URL. +hasTabs: true +eleventyNavigation: + key: carbon-txt-api-check-by-url + title: Check by carbon.txt URL + order: 4 +--- + +# 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. + +{% set endpoint = 'url' %} +{% include 'partials/carbon-txt-endpoint.njk' %} + +## Payload + +The request should include a JSON-encoded body with the carbon.txt file contents encoded as the `url` parameter. + +An example with CURL: + +```bash +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 +``` + +
    +
    +
    +

    Important

    +

    Please note that the carbon.txt validator does not follow redirects. It will return a failure result if it encounters a redirect, and will flag this error in the logs.

    +
    +
    +
    + +{% set successCodeBlock %} +```json +{ + "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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/model-cards). +{% endset %} + +{% include 'partials/carbon-txt-results.njk' %} From a72221c12f099f381797f40216795216051831d7 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:53:52 +0800 Subject: [PATCH 09/13] overview partial --- src/_includes/partials/carbon-txt-overview.njk | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 src/_includes/partials/carbon-txt-overview.njk diff --git a/src/_includes/partials/carbon-txt-overview.njk b/src/_includes/partials/carbon-txt-overview.njk new file mode 100644 index 0000000..e5221ff --- /dev/null +++ b/src/_includes/partials/carbon-txt-overview.njk @@ -0,0 +1,10 @@ +[carbon.txt](https://carbontxt.org) makes sustainability data easier to discover and use on the web. Carbon.txt is a single, discoverable location on any web domain for public, machine-readable, sustainability data relating to that company. + +It’s a web-first, *connect not collect* style approach, of most benefit to those interested in scraping the structured data companies have to publish according to national laws. Designed to be extended by default, we see carbon.txt becoming essential infrastructure for sustainability data services crunching available numbers and sharing the stories it can tell. + +## Why carbon.txt? + +1. **Discovery of sustainability data continues to be a problem.** Our research with Wikirate made it abundantly clear that without new, webby approaches, sustainability data will continue to be hard to find or out of date. +1. **Changes in the law mean that lots of firms will need to publish all kinds of sustainability data that previously they didn’t have to.** The law literally says they need to publish this data online, free of charge for the public to see, and there are significant GDPR-scale fees for non-compliance. +1. **New standards mean that this data will be comparable, machine-readable, and likely across different parts of the world.** This could make verifying claims and identifying greenwashing easier, if it’s done right. +1. **Carbon.txt is our open-source project to make this sustainability information easier to discover.** Carbon.txt is a spec that defines predictable, consistent places on any website to publish sustainability data so that both humans and machines can find it. From bf96ff6f2cfb688252e807556dc12793c78a03e4 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:54:07 +0800 Subject: [PATCH 10/13] use partial for overview --- src/docs/carbon-txt/overview.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/src/docs/carbon-txt/overview.md b/src/docs/carbon-txt/overview.md index 2aa38ec..340c56d 100644 --- a/src/docs/carbon-txt/overview.md +++ b/src/docs/carbon-txt/overview.md @@ -11,20 +11,11 @@ eleventyNavigation: # Carbon.txt - Overview -carbon.txt makes sustainability data easier to discover and use on the web. Carbon.txt is a single, discoverable location on any web domain for public, machine-readable, sustainability data relating to that company. - -It’s a web-first, *connect not collect* style approach, of most benefit to those interested in scraping the structured data companies have to publish according to national laws. Designed to be extended by default, we see carbon.txt becoming essential infrastructure for sustainability data services crunching available numbers and sharing the stories it can tell. - -## Why carbon.txt? - -1. **Discovery of sustainability data continues to be a problem.** Our research with Wikirate made it abundantly clear that without new, webby approaches, sustainability data will continue to be hard to find or out of date. -1. **Changes in the law mean that lots of firms will need to publish all kinds of sustainability data that previously they didn’t have to.** The law literally says they need to publish this data online, free of charge for the public to see, and there are significant GDPR-scale fees for non-compliance. -1. **New standards mean that this data will be comparable, machine-readable, and likely across different parts of the world.** This could make verifying claims and identifying greenwashing easier, if it’s done right. -1. **Carbon.txt is our open-source project to make this sustainability information easier to discover.** Carbon.txt is a spec that defines predictable, consistent places on any website to publish sustainability data so that both humans and machines can find it. +{% include 'partials/carbon-txt-overview.njk' %} ## These docs -The documentation on this website is aimed at developers looking to build additional tooling that extends carbon.txt - primarily through plugins and other extensions to the [carbon.txt validator](https://github.com/thegreenwebfoundation/carbon-txt-validator). General information about carbon.txt for a non-technical audience is available on the carbon.txt website. +The documentation in this section is aimed at developers looking to build additional tooling that extends carbon.txt - primarily through plugins and other extensions to the [carbon.txt validator](https://github.com/thegreenwebfoundation/carbon-txt-validator). General information about carbon.txt for a non-technical audience is available on the [carbon.txt website](https://carbontxt.org). ## Other carbon.txt Tools From bab3b1499a6cdbf8f210f996a3837496f7f60b06 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:54:20 +0800 Subject: [PATCH 11/13] edit overview content --- src/docs/api/carbon-txt/overview.md | 190 ++++++++++++---------------- 1 file changed, 82 insertions(+), 108 deletions(-) diff --git a/src/docs/api/carbon-txt/overview.md b/src/docs/api/carbon-txt/overview.md index 6815de5..c7abaf8 100644 --- a/src/docs/api/carbon-txt/overview.md +++ b/src/docs/api/carbon-txt/overview.md @@ -14,111 +14,85 @@ eleventyNavigation: The carbon.txt validator API allows you to validate the syntax and content of carbon.txt files, and to look up the carbon.txt file for a given domain. -# Authentication - -To use the carbon.txt validation API, you will need to authenticate using a Green Web Foundation API key, available by logging into the [Green Web Portal](https://admin.thegreenwebfoundation.org). Register or log into an existing account, then navigate to the API keys section in the main navigation - ou will be asked to provide some information on your planned use case, and to accept our privacy policy before creating your first key. You may create up to a maximum of 3 API keys by default. - -Once you have created a key, you can use it to authenticate your requests to the carbon.txt validation API by passing the `X-Api-Key` header with your requests. By default, requests are rate limited to 2 per second per API key. - -If you need more keys, or a raised rate limit, please get in touch with our support team and we'll be happy to help. - - -[Interactive OpenAPI documentation](https://carbon-txt-api.greenweb.org/api/docs) for the API is also available, and has full details of all request and response parameters. - -# Usage - -The carbon.txt validation API allows carbon.txt files to be validated by direct upload, provided at a specific URL, or a fully qualified domain name. - -All carbon.txt validation endpoints are available from the [carbon-txt-api.greenweb.org](https://carbon-txt-api.greenweb.org) domain. - -## Validating a carbon.txt file by direct upload - -To validate a carbon.txt file by uploading contents directly, make a POST request to the `/api/validate/file` endpoint, passing a JSON-encoded body with the carbon.txt file contents encoded as the `text_contents` parameter. An example with CURL: - - -```bash -curl -X POST \ - -H "Content-Type: application/json" \ - -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ - --data "{\"text_contents\": \"version='0.5'\n[org]\ndisclosures=[{ doc_type='web-page', url='https://example.com'}]\" }" \ - https://carbon-txt-api.greenweb.org/api/validate/file -``` - -## Validating a carbon.txt file by url - -To validate a carbon.txt file already available at a public URL, make a POST request to the `/api/validate/url` endpoint, passing a JSON-encoded body with the carbon.txt file url passed as the `url` parameter. An example with CURL: - - -```bash -curl -X POST \ - -H "Content-Type: application/json" \ - -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ - --data "{\"url\": \"https://thegreenwebfoundation.org/carbon.txt\" }" \ - https://carbon-txt-api.greenweb.org/api/validate/url -``` - -## Looking up the carbon.txt file for a domain - -To look up and validate the carbon.txt file for a given domain, make a POST request to the `/api/validate/domain` endpoint, passing a JSON-encoded body with the fully-qualified domain name passed as the `domain` parameter. - - -This method will search for a carbon.txt at both the paths `/carbon.txt` and `/.well-known/carbon.txt`, and will follow any [delegation rules](https://carbontxt.org/faq) set up in DNS TXT records or HTTP headers on the queried domain. - -An example with CURL: - - -```bash -curl -X POST \ - -H "Content-Type: application/json" \ - -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ - --data "{\"domain\": \"developers.thegreenwebfoundation.org\" }" \ - https://carbon-txt-api.greenweb.org/api/validate/domain -``` - -## Understanding the validator response. - -All three methods of validating a carbon.txt file return a response in the same format - a JSON object such as the following: - -```json -{ - "success": true, - "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 a boolean indicating whether or not a carbon.txt file was succesfully found and parsed. - - The contents of the carbon txt file, serialized as JSON, inside the `data` field, if the validation was succesful. - - 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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/model-cards). - - If you validated a url or domain, a `url` field will be returned with the canonical url of the file found. - - 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. +{% include 'partials/carbon-txt-overview.njk' %} + +## These docs + +The documentation in this section is aimed at developers looking to use the carbon.txt validator API provided by the Green Web Foundation to discover, validate, and parse carbon.txt files and their contents. General information about carbon.txt for a non-technical audience is available on the [carbon.txt website](https://carbontxt.org). + +This documentation covers: + +- [Authenticating](/api/carbon-txt-/authentication) requests made to the carbon.txt validator API +- Using the carbon.txt validator API to discover and parse carbon.txt files on a [given web domain](/api/carbon-txt-/check-by-domain) +- Using the carbon.txt validator API to discover and parse carbon.txt files at a [specific public URL](/api/carbon-txt-/check-by-url) +- Using the carbon.txt validator API to parse [carbon.txt content directly](/api/carbon-txt-/check-by-content) + +## Other carbon.txt Tools + +Below are a collection of tools that you can use to get started creating a carbon.txt file for your organisation, or to check the contents of an existing carbon.txt file. + +
    +
    +
    +

    + + + +Quickstart guide?

    +

    Learn how to create a carbon.txt file for your organisation, upload it to your domain, and check that it is valid.

    +
    +
    +
    + Go to guide +
    +
    + +
      +
    • +
      +

      File builder +

      + Create a carbon.txt file for your organisation or website. +
      + Use the builder +
      +
      +
      • +
    • +
      +

      Validator +

      + Check the syntax of a carbon.txt file and view its content. +
      + Use the validator +
      +
      +
      • +
    • +
      +

      Python package

      + Create and validate carbon.txt files using our reference implementation in Python. +
      + Go to the documentation +
      +
      +
      • +
    • +
      +
      +

      Syntax reference

      + Learn about all the details of the carbon.txt format from our syntax specification. +
      +
      + Go to the reference +
      +
      +
      • +
    + +## Keep updated + +To follow the carbon.txt project, you can: + +Follow us on LinkedIn +Subscribe to our montlhy newsletter From 20075163fb91d766a48d8033e392808fa3e929b1 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Mon, 1 Jun 2026 17:09:20 +0800 Subject: [PATCH 12/13] add js example --- src/docs/api/carbon-txt/check-by-content.md | 39 +++++++++++++++++++-- src/docs/api/carbon-txt/check-by-domain.md | 35 +++++++++++++++--- src/docs/api/carbon-txt/check-by-url.md | 34 +++++++++++++++--- 3 files changed, 96 insertions(+), 12 deletions(-) diff --git a/src/docs/api/carbon-txt/check-by-content.md b/src/docs/api/carbon-txt/check-by-content.md index 30a1f0b..39284ba 100644 --- a/src/docs/api/carbon-txt/check-by-content.md +++ b/src/docs/api/carbon-txt/check-by-content.md @@ -20,15 +20,48 @@ To validate a carbon.txt file by uploading contents directly, make a `POST` requ The request should include a JSON-encoded body with the carbon.txt file contents encoded as the `text_contents` parameter. -An example with CURL: + +
      +
    1. JavaScript
      2. +
    2. cURL
      3. +
    -```bash +
    +{% set code %} +fetch("https://carbon-txt-api.greenweb.org/api/validate/file", { + method: "POST", + headers: { + "X-Api-Key": gwf_xxxxxxx.xxxxxxxxxxxxxxxxx, + }, + body: JSON.stringify({ text_contents: version="0.5" + last_updated=2026-06-01 + + [org] + disclosures = [ + { doc_type="web-page", url="https://example.com" }, + ] + }) +}) +{% endset %} + +{% codeSnippet code, 'js' %} + +
    + +
    +{% set code %} curl -X POST \ -H "Content-Type: application/json" \ -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ --data "{\"text_contents\": \"version='0.5'\n[org]\ndisclosures=[{ doc_type='web-page', url='https://example.com'}]\" }" \ https://carbon-txt-api.greenweb.org/api/validate/file -``` +{% endset %} + +{% codeSnippet code, 'curl' %} + +
    +
    + {% set successCodeBlock %} ```json diff --git a/src/docs/api/carbon-txt/check-by-domain.md b/src/docs/api/carbon-txt/check-by-domain.md index 07bc123..c7fc348 100644 --- a/src/docs/api/carbon-txt/check-by-domain.md +++ b/src/docs/api/carbon-txt/check-by-domain.md @@ -20,17 +20,42 @@ To validate a carbon.txt file by hosted at a public domain, make a `POST` reques The request should include a JSON-encoded body with the carbon.txt file contents encoded as the `domain` parameter. -An example with CURL: + +
      +
    1. JavaScript
      2. +
    2. cURL
      3. +
    -```bash +
    +{% set code %} +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 }) +}) +{% endset %} + +{% codeSnippet code, 'js' %} + +
    + +
    +{% set code %} curl -X POST \ -H "Content-Type: application/json" \ -H "X-Api-Key: gwf_xxxxxxx.xxxxxxxxxxxxxxxxx" \ - --data "{\"domain\": \"https://example.com/carbon.txt\" }" \ + --data "{\"domain\": \"example.com/\" }" \ https://carbon-txt-api.greenweb.org/api/validate/domain -``` +{% endset %} + +{% codeSnippet code, 'curl' %} -
    +
    + + +

    Important

    diff --git a/src/docs/api/carbon-txt/check-by-url.md b/src/docs/api/carbon-txt/check-by-url.md index f266f96..07c61ea 100644 --- a/src/docs/api/carbon-txt/check-by-url.md +++ b/src/docs/api/carbon-txt/check-by-url.md @@ -20,17 +20,43 @@ To validate a carbon.txt file by hosted at a public URL, make a `POST` request t The request should include a JSON-encoded body with the carbon.txt file contents encoded as the `url` parameter. -An example with CURL: + +
      +
    1. JavaScript
      2. +
    2. cURL
      3. +
    -```bash +
    +{% set code %} +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 }) +}) +{% endset %} + +{% codeSnippet code, 'js' %} + +
    + +
    +{% set code %} 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 -``` +{% endset %} + +{% codeSnippet code, 'curl' %} -
    +
    +
    +     + +

    Important

    From c93f31bf228865b54476bd1de775143f41588e15 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Tue, 2 Jun 2026 18:19:53 +0800 Subject: [PATCH 13/13] add co2.js carbon.txt docs --- src/docs/co2js/tutorials/check-carbon-txt.md | 162 +++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 src/docs/co2js/tutorials/check-carbon-txt.md diff --git a/src/docs/co2js/tutorials/check-carbon-txt.md b/src/docs/co2js/tutorials/check-carbon-txt.md new file mode 100644 index 0000000..de01438 --- /dev/null +++ b/src/docs/co2js/tutorials/check-carbon-txt.md @@ -0,0 +1,162 @@ +--- +title: "Check a domain for carbon.txt" +description: "In this tutorial, you will install CO2.js in a Node environment. Then, you will check a domain to see if they are hosting a valid carbon.txt file." +eleventyNavigation: + key: check-carbon-txt + title: "Check a domain for carbon.txt" + # parent: overview + sectionTitle: Tutorials + order: 14 +--- + +# {{ title }} + +## 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](/api/carbon-txt/overview/) to return results. You can learn more about the carbon.txt project at [https://carbontxt.org](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. + +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/thegreenwebfoundation/gitpod-node-starter) + +### 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. + +```bash +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. + +```bash +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. + +```js +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](http://admin.thegreenwebfoundation.org/provider-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. + +```js +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: + +```bash +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. + +{% set successCodeBlock %} +```json +{ + "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](https://carbon-txt-validator.readthedocs.io/en/latest/plugins.html). Currently the API provides plugins to parse [CSRD reports](https://finance.ec.europa.eu/financial-markets/company-reporting-and-auditing/company-reporting/corporate-sustainability-reporting_en) and [AI model cards](https://huggingface.co/docs/hub/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. +{% endset %} + +{% include 'partials/carbon-txt-results.njk' %}