Add documentation for carbon.txt HTTP API

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).

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.

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.

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 - 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.
+
+If you need more keys, or a raised rate limit, please <a href="mailto:support@greenweb.org?subject=API%20key%20enquiry">get in touch</a> 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.

src/docs/api/carbon-txt/carbon-txt.json

@@ -0,0 +1,9 @@
+{
+  "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"
+}

src/docs/api/carbon-txt/check-by-content.md

@@ -0,0 +1,111 @@
+---
+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.
+
+<seven-minute-tabs>
+   <ol role="tablist" aria-label="Select a programming language to preview">
+    <li><a href="#js" role="tab" aria-selected="true">JavaScript</a></li>
+    <li><a href="#curl" role="tab">cURL</a></li>
+   </ol>
+
+   <div id="js" role="tabpanel">
+{% 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' %}
+
+   </div>
+
+   <div id="curl" role="tabpanel">
+{% 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' %}
+
+   </div>
+   </div>
+   </seven-minute-tabs>
+
+{% set successCodeBlock %}
+```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).
+{% endset %}
+
+{% include 'partials/carbon-txt-results.njk' %}

src/docs/api/carbon-txt/check-by-domain.md

@@ -0,0 +1,116 @@
+---
+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.
+
+<seven-minute-tabs>
+   <ol role="tablist" aria-label="Select a programming language to preview">
+    <li><a href="#js" role="tab" aria-selected="true">JavaScript</a></li>
+    <li><a href="#curl" role="tab">cURL</a></li>
+   </ol>
+
+   <div id="js" role="tabpanel">
+{% 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' %}
+
+   </div>
+
+   <div id="curl" role="tabpanel">
+{% set code %}
+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
+{% endset %}
+
+{% codeSnippet code, 'curl' %}
+
+   </div>
+   </seven-minute-tabs>
+
+<div class="alert alert-info my-3">
+  <div class="items-start">
+    <div>
+      <h2 class="font-bold my-3 gap-2 flex items-center">Important</h2>
+      <p class="text-lg">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.</p>
+    </div>
+  </div>
+</div>
+
+
+{% 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' %}