Developer Documentation & API

Tools, APIs, and integration guides for building and connecting AI-native websites.

⚡ Quick Start

Get started with the Digital Karma Web Federation in 5 minutes:

Create manifest.json
{ "name": "Your Site Name", "description": "Site description", "url": "https://yoursite.com", "federation_version": "6.1", "last_updated": "2026-01-15T10:00:00Z", "contact": { "email": "admin@yoursite.com" }, "ai_endpoints": [ "/ai/health.json", "/ai/catalog.json" ] }
Create health.json
{ "status": "healthy", "last_check": "2026-01-15T10:00:00Z", "uptime_percent": 99.9, "response_time_ms": 45, "metrics": { "total_pages": 20, "total_datasets": 3, "last_content_update": "2026-01-15T09:00:00Z" } }
Add Schema.org markup
<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "WebSite", "name": "Your Site Name", "url": "https://yoursite.com" } </script>
Validate your implementation
$ curl https://yoursite.com/ai/manifest.json $ node validators/validate-ai-folder.js
Submit to federation
Fill out the submission form and you're live!

📡 Public API Endpoints

Machine-readable data endpoints for AI agents and developers.

GET /ai/manifest.json

Site Identity & Discovery

Returns site metadata, available endpoints, and federation information.

curl https://www.aiwebsitesystems.com/ai/manifest.json

GET /ai/health.json

System Health Status

Real-time health metrics and operational status.

curl https://www.aiwebsitesystems.com/ai/health.json

GET /ai/catalog.json

Content Catalog

Complete inventory of site content and resources.

curl https://www.aiwebsitesystems.com/ai/catalog.json

GET /ai/karma.json

Digital Karma Score

Trust and quality scoring with signal breakdown.

curl https://www.aiwebsitesystems.com/ai/karma.json

GET /ai/federation.json

Federation Network Topology

Complete map of federated sites and relationships.

curl https://www.aiwebsitesystems.com/ai/federation.json

GET /api/listings.json

Directory Listings

All systems in the AI Website Systems directory.

curl https://www.aiwebsitesystems.com/api/listings.json

GET /llm.txt

LLM-Optimized Summary

Plain text site overview optimized for language models.

curl https://www.aiwebsitesystems.com/llm.txt

POST /api/submit-system.json

Submit System

Programmatically submit a new system to the directory.

curl -X POST https://www.aiwebsitesystems.com/api/submit-system.json \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your System",
    "url": "https://yoursystem.com",
    "category": "static-ai-sites",
    "description": "System description"
  }'

🛠️ Developer Tools

Scripts and utilities for building and maintaining AI-native websites.

Federation Validator

Validates your /ai/ folder structure and endpoint compliance.

$ node validators/validate-ai-folder.js

Features:

Checks for required files (manifest.json, health.json, etc.)
Validates JSON structure and required fields
Reports compliance level (Basic, Standard, Full, Elite)
Suggests improvements

Download validator →

Karma Score Calculator

Calculates your Digital Karma Score across 7 quality signals.

$ python ai/calculate_karma.py

Output:

Overall score (0.00 - 1.00)
Individual signal scores
Badge level (Bronze, Pro, Elite)
Suggestions for improvement

Download calculator →

Schema Validator

Validates Schema.org JSON-LD structured data.

$ node validators/validate-json-schema.js

Validates:

JSON-LD syntax correctness
Schema.org type usage
Required property presence
URL and date format validity

Download validator →

Link Checker

Validates all links in your AI endpoints and federation network.

$ node validators/validate-links.js

Checks:

All URLs return 200 OK
Federation links are bidirectional
Endpoints are accessible
Response time metrics

Download checker →

Data Harvester Template

Automated data collection script template for building directories.

$ python ai/harvest_data.py

Features:

Fetch data from federation endpoints
Parse Schema.org markup
Generate catalog.json automatically
Schedule periodic updates

Download template →

💻 Integration Examples

Python: Fetch Federation Data

import requests
import json

# Fetch manifest from a federated site
response = requests.get('https://www.aiwebsitesystems.com/ai/manifest.json')
manifest = response.json()

print(f"Site: {manifest['name']}")
print(f"Version: {manifest['federation_version']}")
print(f"Endpoints: {', '.join(manifest['ai_endpoints'])}")

# Fetch all federation members
federation = requests.get('https://www.aiwebsitesystems.com/ai/federation.json').json()
for site in federation['federation_sites']:
    print(f"- {site['name']}: {site['url']}")

JavaScript: Validate Karma Score

async function checkKarmaScore(siteUrl) {
  try {
    const response = await fetch(`${siteUrl}/ai/karma.json`);
    const karma = await response.json();
    
    console.log(`Karma Score: ${karma.score}`);
    console.log(`Badge: ${karma.badge}`);
    console.log('Signal Breakdown:');
    for (const [signal, value] of Object.entries(karma.signals)) {
      console.log(`  ${signal}: ${value}`);
    }
    
    return karma.score >= 0.70; // Minimum threshold
  } catch (error) {
    console.error('Failed to fetch karma score:', error);
    return false;
  }
}

// Usage
checkKarmaScore('https://www.aiwebsitesystems.com');

Bash: Automated Health Check

#!/bin/bash
# health-check.sh - Monitor federation site health

SITE_URL="https://www.aiwebsitesystems.com"

# Check health endpoint
health=$(curl -s "${SITE_URL}/ai/health.json")
status=$(echo $health | jq -r '.status')

if [ "$status" = "healthy" ]; then
  echo "✓ Site is healthy"
  exit 0
else
  echo "✗ Site is $status"
  # Send alert
  exit 1
fi

Node.js: Build a Federation Crawler

const axios = require('axios');

async function crawlFederation(startUrl) {
  const visited = new Set();
  const queue = [startUrl];
  const sites = [];

  while (queue.length > 0) {
    const url = queue.shift();
    if (visited.has(url)) continue;
    visited.add(url);

    try {
      const { data } = await axios.get(`${url}/ai/manifest.json`);
      sites.push({
        name: data.name,
        url: data.url,
        endpoints: data.ai_endpoints
      });

      // Add related sites to queue
      if (data.related_sites) {
        queue.push(...data.related_sites);
      }
    } catch (error) {
      console.error(`Failed to fetch ${url}:`, error.message);
    }
  }

  return sites;
}

// Usage
crawlFederation('https://www.aiwebsitesystems.com')
  .then(sites => console.log(`Found ${sites.length} federated sites`));

📦 SDKs & Libraries

Official and community-maintained libraries for working with the Digital Karma Web Federation.

dk-sdk-js (JavaScript/TypeScript)

Official JavaScript SDK for federation integration.

$ npm install @digitalkarma/sdk

import { FederationClient } from '@digitalkarma/sdk';

const client = new FederationClient('https://www.aiwebsitesystems.com');
const manifest = await client.getManifest();
const karma = await client.getKarmaScore();

Status: Coming Soon

digital-karma-python (Python)

Python library for federation crawling and scoring.

$ pip install digital-karma

from digital_karma import FederationClient

client = FederationClient('https://www.aiwebsitesystems.com')
manifest = client.get_manifest()
score = client.calculate_karma_score()

Status: Coming Soon

⚠️ API Rate Limits

All public API endpoints are currently unlimited and free. However, we ask that you:

Cache responses appropriately (endpoints update hourly)
Don't hammer endpoints with rapid requests
Identify your application in the User-Agent header

Rate limits may be introduced in the future. We'll provide advance notice.

🌐 CORS & Cross-Origin Access

All API endpoints support CORS and can be accessed from any origin:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Need Help?

Have questions about integration or need technical support?

Browse Knowledge Base Contact Support