{
  "name": "wellknown-fetch",
  "summary": "Fetches and parses a domain's well-known files -- security.txt (RFC 9116), ads.txt and humans.txt -- returning typed fields, seller records and a cross-file summary in one call.",
  "rationale": "It needs the network and a hardened client: the files are named by a stranger, so a naive fetch of /ads.txt is an SSRF probe, and the value is the parse -- PGP-signed security.txt fields, ads.txt split into DIRECT/RESELLER records -- an agent would otherwise build and maintain itself.",
  "family": "feeds",
  "price_usd": "0.002",
  "free": false,
  "timeout_ms": 12000,
  "max_timeout_seconds": 33,
  "input_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "domain": {
        "description": "Fully qualified domain name whose files are fetched over https, up to 253 characters; it is trimmed, lowercased and stripped of trailing dots, and IP literals, single-label names and private suffixes are refused.",
        "type": "string",
        "minLength": 1,
        "maxLength": 253
      },
      "files": {
        "description": "Which files to fetch, from security.txt (read at /.well-known/security.txt), ads.txt and humans.txt (read at the root); duplicates collapse, and the default is all three.",
        "minItems": 1,
        "maxItems": 3,
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "security.txt",
            "ads.txt",
            "humans.txt"
          ]
        }
      }
    },
    "required": [
      "domain"
    ],
    "additionalProperties": false
  },
  "input_example": {
    "domain": "example.com"
  },
  "output_example": {
    "domain": "example.com",
    "files_requested": [
      "security.txt",
      "ads.txt",
      "humans.txt"
    ],
    "security_txt": {
      "requested": true,
      "present": true,
      "status": 200,
      "url": "https://example.com/.well-known/security.txt",
      "contact": [
        "mailto:security@example.com",
        "https://example.com/security-contact"
      ],
      "expires": "2027-01-01T00:00:00.000Z",
      "is_expired": false,
      "encryption": [
        "https://example.com/pgp-key.txt"
      ],
      "acknowledgments": [
        "https://example.com/hall-of-fame"
      ],
      "preferred_languages": "en, fr",
      "canonical": [
        "https://example.com/.well-known/security.txt"
      ],
      "policy": [
        "https://example.com/security-policy"
      ],
      "hiring": [
        "https://example.com/jobs"
      ],
      "signed": false,
      "field_count": 9
    },
    "ads_txt": {
      "requested": true,
      "present": true,
      "status": 200,
      "url": "https://example.com/ads.txt",
      "records": [
        {
          "advertising_system": "greenadexchange.com",
          "publisher_id": "12345",
          "relationship": "DIRECT",
          "certification_authority_id": "d75815a79",
          "line": 4
        },
        {
          "advertising_system": "blueadexchange.com",
          "publisher_id": "xf7",
          "relationship": "RESELLER",
          "certification_authority_id": null,
          "line": 5
        },
        {
          "advertising_system": "silverssp.com",
          "publisher_id": "9675",
          "relationship": "DIRECT",
          "certification_authority_id": null,
          "line": 6
        }
      ],
      "records_total": 3,
      "records_truncated": false,
      "direct_count": 2,
      "reseller_count": 1,
      "variables": [
        {
          "name": "CONTACT",
          "value": "adops@example.com"
        }
      ],
      "variables_truncated": false,
      "invalid_lines": 0
    },
    "humans_txt": {
      "requested": true,
      "present": true,
      "status": 200,
      "url": "https://example.com/humans.txt",
      "text": "/* TEAM */\nWebmaster: Jane Doe\nSite: example.com\n\n/* THANKS */\nEveryone.\n",
      "truncated": false,
      "bytes": 73
    },
    "normalised": {
      "files_present": [
        "ads.txt",
        "humans.txt",
        "security.txt"
      ],
      "security_contacts": [
        "mailto:security@example.com",
        "https://example.com/security-contact"
      ],
      "security_expires": "2027-01-01T00:00:00.000Z",
      "security_expired": false,
      "security_signed": false,
      "ads_sellers": 3,
      "ads_direct": 2,
      "ads_reseller": 1
    },
    "fetched_at": "2026-08-26T18:00:00.000Z"
  },
  "errors": [
    "invalid_input",
    "blocked_target",
    "unreachable_target",
    "upstream_timeout",
    "too_large",
    "internal"
  ]
}