Skip to content

API-DOCS-DEPLOYED.md

Latest commit

 

History

History
247 lines (192 loc) · 5.48 KB

API-DOCS-DEPLOYED.md

File metadata and controls

247 lines (192 loc) · 5.48 KB

API Documentation Deployment Summary

Date: 2025-10-04 Status: ✅ DEPLOYED AND LIVE

Documentation URLs (Public LLM Access)

Markdown Format

https://api.chitty.cc/docs
https://id.chitty.cc/docs
https://auth.chitty.cc/docs
https://sync.chitty.cc/docs
https://ai.chitty.cc/docs
https://mcp.chitty.cc/docs

JSON Format (LLM-Optimized)

https://api.chitty.cc/docs/json
https://id.chitty.cc/docs/json
https://auth.chitty.cc/docs/json

Example Response:

{
  "version": "2.0.0",
  "title": "ChittyOS Platform API",
  "services": {
    "chittyid": {...},
    "auth": {...},
    "sync": {...},
    "ai": {...},
    "mcp": {...}
  },
  "examples": {...}
}

OpenAPI 3.0 Specification

https://api.chitty.cc/docs/openapi
https://id.chitty.cc/docs/openapi

Example Response:

{
  "openapi": "3.0.0",
  "info": {
    "title": "ChittyOS Platform API",
    "version": "2.0.0"
  },
  "servers": [...],
  "paths": {...}
}

What's Documented

1. ChittyID Service (id.chitty.cc)

  • Health check: /health
  • Generate ID: POST /generate (pipeline-only, proxies to central authority)
  • Validate: GET /validate/{id}
  • Metadata: GET /metadata/{id}

2. Authentication Service (auth.chitty.cc)

  • Create token: POST /api/auth/token
  • Verify token: POST /api/auth/verify
  • Refresh token: POST /api/auth/refresh
  • Revoke session: DELETE /api/auth/session/{id}

3. Sync Service (api.chitty.cc, sync.chitty.cc)

  • Projects: /api/project (GET, POST, PUT, DELETE)
  • Sessions: /api/session (GET, POST, PUT, DELETE)
  • Topics: /api/topic (GET, POST, PUT, DELETE)
  • Todos: /api/todos (GET, POST, PUT, DELETE)
  • Status: /api/status

Platform sync endpoints:

  • /neon - PostgreSQL sync
  • /notion - Notion sync
  • /github - GitHub sync
  • /drive - Google Drive sync
  • /cloudflare - R2/KV/D1 sync

4. AI Gateway (ai.chitty.cc)

  • Chat: POST /v1/chat/completions (OpenAI compatible)
  • Embeddings: POST /v1/embeddings
  • Models: GET /v1/models

5. MCP Portal (mcp.chitty.cc, portal.chitty.cc)

  • Health: /health

LLM Access Instructions

For AI Models/Assistants

To access ChittyOS API documentation:

Primary URL: https://api.chitty.cc/docs/json

This returns structured JSON with:

  • Complete service catalog
  • Endpoint specifications
  • Request/response schemas
  • Working code examples
  • Error codes
  • Authentication flows

Alternative formats:

  • Markdown: https://api.chitty.cc/docs
  • OpenAPI: https://api.chitty.cc/docs/openapi

Curl Examples

# Get full JSON documentation
curl https://api.chitty.cc/docs/json | jq .

# Get Markdown documentation
curl https://api.chitty.cc/docs

# Get OpenAPI specification
curl https://api.chitty.cc/docs/openapi

# Access from any service domain
curl https://id.chitty.cc/docs/json
curl https://auth.chitty.cc/docs/json
curl https://ai.chitty.cc/docs/json

Technical Implementation

Worker Integration

  • Service: src/services/docs.js
  • Handler: handleDocs(context)
  • Routes: All service domains have /docs path intercepted

Route Configuration

Added to wrangler.optimized.toml:

{ pattern = "docs.chitty.cc/*", zone_name = "chitty.cc" }

Platform Worker

Documentation accessible via /docs on any service domain:

// API Documentation - accessible from any domain
if (pathname.startsWith('/docs')) {
  const context = buildContext(request, env, ctx);
  return handleDocs(context);
}

Response Formats

Markdown (/docs):

  • Content-Type: text/markdown; charset=utf-8
  • Human-readable format
  • GitHub-compatible markdown

JSON (/docs/json):

  • Content-Type: application/json
  • Structured data for LLMs
  • Complete endpoint specifications
  • Code examples included

OpenAPI (/docs/openapi):

  • Content-Type: application/json
  • OpenAPI 3.0 specification
  • Compatible with Swagger/Postman

CORS Headers

All documentation endpoints include:

Access-Control-Allow-Origin: *

This allows cross-origin access from any LLM or application.

Files Created

  1. API-DOCUMENTATION.md - Comprehensive markdown documentation
  2. src/services/docs.js - Documentation service handler
  3. API-DOCS-DEPLOYED.md - This deployment summary

Verification

# Test all formats
curl -s https://api.chitty.cc/docs | head -30
curl -s https://api.chitty.cc/docs/json | jq '.version, (.services | keys)'
curl -s https://api.chitty.cc/docs/openapi | jq '.info'

# Verify from different service domains
curl -s https://id.chitty.cc/docs/json | jq '.services.chittyid.endpoints[].path'
curl -s https://auth.chitty.cc/docs/json | jq '.services.auth.endpoints[].path'
curl -s https://ai.chitty.cc/docs/json | jq '.services.ai.endpoints[].path'

Expected Results:

  • ✅ All endpoints return documentation
  • ✅ JSON is properly formatted
  • ✅ OpenAPI spec is valid
  • ✅ CORS headers present
  • ✅ Accessible from all service domains

For LLMs: Quick Start

To understand the ChittyOS API:

  1. Fetch documentation:

    GET https://api.chitty.cc/docs/json

  2. Review structure:

    • services - All available services
    • endpoints - API endpoints per service
    • examples - Working code samples
    • errorCodes - HTTP status codes

  3. Use examples: The examples section contains ready-to-use curl commands for common workflows.

Status: 🟢 LIVE Deployment: chittyos-platform-production Version: 2.0.0 Last Updated: 2025-10-04