ChittyOS Platform API Documentation

Version: 2.0.0 Base URL: https://{service}.chitty.cc Account: ChittyCorp CI/CD (0bc21e3a5a9de1a4cc843be9c3e98121) Worker: chittyos-platform-production

ChittyID Service - id.chitty.cc
Authentication Service - auth.chitty.cc
Sync Service - sync.chitty.cc / api.chitty.cc
AI Gateway - ai.chitty.cc
MCP Portal - mcp.chitty.cc / portal.chitty.cc
Error Codes
Rate Limits
Examples

ChittyID Service

Base URL: https://id.chitty.cc

The ChittyID service is a pipeline-only architecture that proxies all ID generation requests to the central ChittyID authority. Local generation is strictly prohibited.

Endpoints

Health Check

GET /health

Response:

{
  "service": "chitty-id",
  "status": "healthy",
  "mode": "pipeline-only",
  "version": "2.1.0"
}

Generate ChittyID

POST /generate
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body:

{
  "metadata": {
    "entityType": "INFO",
    "description": "User data record"
  },
  "sessionContext": {
    "sessionId": "session-123",
    "project": "my-project"
  }
}

Response (200 OK):

{
  "chittyId": "01-I-NFO-0001-T-25-C-X",
  "source": "id.chitty.cc",
  "pipeline": "chittychat-proxy",
  "note": "Generated by central ChittyID authority",
  "metadata": {
    "entityType": "INFO",
    "description": "User data record"
  },
  "created": "2025-10-04T06:00:00.000Z"
}

Error (401 Unauthorized):

{
  "error": "API key required",
  "message": "Include Authorization: Bearer <api-key> header"
}

Error (502 Bad Gateway):

{
  "error": "ChittyID service unavailable",
  "message": "Central service returned 503",
  "service": "id.chitty.cc",
  "note": "ChittyIDs can ONLY be generated by the central service"
}

Validate ChittyID

GET /validate/{chittyId}

Response (200 OK):

{
  "valid": true,
  "chittyId": "01-I-NFO-0001-T-25-C-X",
  "hasMetadata": true,
  "format": "VV-G-LLL-SSSS-T-YM-C-X"
}

Response (Invalid Format):

{
  "valid": false,
  "error": "Invalid ChittyID format - must be VV-G-LLL-SSSS-T-YM-C-X"
}

Get ChittyID Metadata

GET /metadata/{chittyId}

Response (200 OK):

{
  "metadata": {
    "entityType": "INFO",
    "description": "User data record"
  },
  "sessionContext": {
    "sessionId": "session-123",
    "project": "my-project"
  },
  "created": "2025-10-04T06:00:00.000Z",
  "source": "id.chitty.cc"
}

Response (404 Not Found):

{
  "error": "Metadata not found",
  "chittyId": "01-I-NFO-0001-T-25-C-X"
}

Authentication Service

Base URL: https://auth.chitty.cc

JWT-based authentication with session management and RBAC support.

Endpoints

Health Check

GET /health

Response:

{
  "service": "auth",
  "status": "healthy",
  "features": ["jwt-tokens", "rbac", "session-management"]
}

Create Token

POST /api/auth/token
Content-Type: application/json

Request Body:

{
  "chittyId": "01-P-EO-0001-T-25-C-X",
  "permissions": ["read", "write", "admin"],
  "expiresIn": 3600
}

Response (200 OK):

{
  "access_token": "eyJzdWIiOiIwMS1QLUVPLTAwMDEtVC0yNS1DLVgiLCJpYXQiOjE2OTk...","
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write admin"
}

Error (400 Bad Request):

{
  "error": "ChittyID required"
}

Verify Token

POST /api/auth/verify
Authorization: Bearer <token>

Response (200 OK):

{
  "valid": true,
  "chittyId": "01-P-EO-0001-T-25-C-X",
  "permissions": ["read", "write", "admin"],
  "expires": 1699999999
}

Error (401 Unauthorized):

{
  "valid": false,
  "error": "Invalid or expired token"
}

Refresh Token

POST /api/auth/refresh
Authorization: Bearer <old-token>

Response (200 OK):

{
  "access_token": "new_token_here",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write admin"
}

Revoke Session

DELETE /api/auth/session/{sessionId}

Response (200 OK):

{
  "revoked": true,
  "sessionId": "session-123"
}

Sync Service

Base URLs:

https://sync.chitty.cc
https://api.chitty.cc (alias)

Platform Integration Hub for cross-session synchronization, project management, and topic categorization.

Architecture

The Sync service provides two layers:

Platform-Specific Endpoints: /neon, /notion, /github, /drive, /cloudflare, /local
Unified Resource APIs: /api/project, /api/session, /api/topic, /api/todos

Core Endpoints

Health Check

GET /health

Response:

{
  "service": "sync",
  "status": "healthy",
  "version": "2.0.0",
  "architecture": "Platform Integration Hub",
  "platforms": ["neon", "notion", "github", "drive", "cloudflare", "local"],
  "resources": ["project", "session", "topic", "todos", "orchestration"],
  "endpoints": {
    "platforms": {
      "neon": "/neon",
      "notion": "/notion",
      "github": "/github",
      "drive": "/drive",
      "cloudflare": "/cloudflare",
      "local": "/local"
    },
    "resources": {
      "project": "/api/project",
      "session": "/api/session",
      "topic": "/api/topic",
      "todos": "/api/todos",
      "orchestrate": "/api/orchestrate",
      "status": "/api/status"
    }
  }
}

Overall Status

GET /api/status

Response:

{
  "service": "sync",
  "version": "2.0.0",
  "timestamp": "2025-10-04T06:00:00.000Z",
  "projects": {
    "total": 5,
    "synced": 4
  },
  "sessions": {
    "total": 3,
    "active": 2
  },
  "topics": {
    "categories": 8,
    "total_conversations": 42
  }
}

Project API

List Projects

GET /api/project

Response:

{
  "projects": [
    {
      "id": "my-project",
      "name": "my-project",
      "lastSync": "2025-10-04T06:00:00.000Z",
      "filesWorked": ["file1.js", "file2.js"],
      "consolidatedTodos": [...]
    }
  ],
  "total": 5,
  "timestamp": "2025-10-04T06:00:00.000Z"
}

Get Project

GET /api/project/{projectId}

Response (200 OK):

{
  "id": "my-project",
  "name": "my-project",
  "lastSync": "2025-10-04T06:00:00.000Z",
  "filesWorked": ["file1.js", "file2.js"],
  "consolidatedTodos": [...],
  "fromGitHub": true
}

Create/Sync Project

POST /api/project
Content-Type: application/json

Request Body:

{
  "id": "my-project",
  "name": "My Project",
  "metadata": {
    "description": "Project description"
  }
}

Response (201 Created):

{
  "success": true,
  "created": true,
  "project": {
    "id": "my-project",
    "name": "My Project",
    "lastSync": "2025-10-04T06:00:00.000Z",
    "syncedToGitHub": true
  },
  "servicesRegistered": false
}

Update Project

PUT /api/project/{projectId}
Content-Type: application/json

Request Body:

{
  "metadata": {
    "updated": "2025-10-04T06:00:00.000Z"
  }
}

Response (200 OK):

{
  "success": true,
  "project": {...}
}

Delete Project

DELETE /api/project/{projectId}

Response (200 OK):

{
  "success": true,
  "deleted": "my-project",
  "note": "Project removed from sync index (GitHub data preserved)"
}

Session API

List Sessions

GET /api/session

Response:

{
  "sessions": [
    {
      "sessionId": "session-123",
      "projectId": "my-project",
      "aiPlatform": "claude",
      "active": true,
      "lastActivity": "2025-10-04T06:00:00.000Z"
    }
  ],
  "total": 3,
  "active": 2,
  "timestamp": "2025-10-04T06:00:00.000Z"
}

Get Session

GET /api/session/{sessionId}

Response (200 OK):

{
  "sessionId": "session-123",
  "projectId": "my-project",
  "aiPlatform": "claude",
  "active": true,
  "created": "2025-10-04T05:00:00.000Z",
  "lastActivity": "2025-10-04T06:00:00.000Z"
}

Register Session

POST /api/session
Content-Type: application/json

Request Body:

{
  "id": "session-123",
  "projectId": "my-project",
  "aiPlatform": "claude",
  "machineId": "machine-456",
  "metadata": {
    "user": "user@example.com"
  }
}

Response (201 Created):

{
  "success": true,
  "session": {
    "id": "session-123",
    "projectId": "my-project",
    "aiPlatform": "claude",
    "created": "2025-10-04T06:00:00.000Z",
    "active": true
  }
}

Update Session (Heartbeat)

PUT /api/session/{sessionId}
Content-Type: application/json

Request Body:

{
  "active": true,
  "metadata": {...}
}

Response (200 OK):

{
  "success": true,
  "sessionId": "session-123",
  "updated": "2025-10-04T06:00:00.000Z",
  "note": "Sessions auto-update via heartbeat mechanism"
}

End Session

DELETE /api/session/{sessionId}

Response (200 OK):

{
  "success": true,
  "sessionId": "session-123",
  "ended": "2025-10-04T06:00:00.000Z"
}

Topic API

List Topics

GET /api/topic

Response:

{
  "topics": [
    {
      "category": "development",
      "count": 15,
      "avgConfidence": 0.85,
      "lastUpdated": "2025-10-04T06:00:00.000Z"
    }
  ],
  "total": 8,
  "timestamp": "2025-10-04T06:00:00.000Z"
}

Get Topic Conversations

GET /api/topic/{category}

Response (200 OK):

{
  "category": "development",
  "conversations": [
    {
      "id": "conv-123",
      "file": "conversation.json",
      "category": "development",
      "subcategories": ["api", "backend"],
      "confidence": 0.9,
      "categorized": "2025-10-04T06:00:00.000Z",
      "content_preview": "Discussion about API endpoints..."
    }
  ],
  "count": 15
}

Categorize Conversation

POST /api/topic
Content-Type: application/json

Request Body:

{
  "id": "conv-123",
  "content": "Full conversation text...",
  "file": "conversation.json",
  "category": "development",
  "subcategories": ["api", "backend"],
  "confidence": 0.9
}

Response (201 Created):

{
  "success": true,
  "conversation": {
    "id": "conv-123",
    "category": "development",
    "subcategories": ["api", "backend"],
    "confidence": 0.9,
    "categorized": "2025-10-04T06:00:00.000Z"
  }
}

Todos API

List Projects with Todos

GET /api/todos

Response:

{
  "projects": [
    {
      "projectId": "my-project",
      "todoCount": 10,
      "lastSync": "2025-10-04T06:00:00.000Z",
      "sessions": 2,
      "pendingTodos": 3,
      "inProgressTodos": 2,
      "completedTodos": 5
    }
  ],
  "total": 5,
  "timestamp": "2025-10-04T06:00:00.000Z"
}

Get Unified Todos

GET /api/todos/{projectId}

Response (200 OK):

{
  "projectId": "my-project",
  "todos": [
    {
      "content": "Fix authentication bug",
      "status": "in_progress",
      "activeForm": "Fixing authentication bug",
      "addedBy": "session-123",
      "addedAt": "2025-10-04T05:00:00.000Z"
    }
  ],
  "lastSync": "2025-10-04T06:00:00.000Z",
  "sessions": ["session-123", "session-456"]
}

Update Unified Todos

POST /api/todos/{projectId}
Content-Type: application/json

Request Body:

{
  "todos": [
    {
      "content": "Fix authentication bug",
      "status": "completed",
      "activeForm": "Fixed authentication bug"
    }
  ]
}

Response (200 OK):

{
  "success": true,
  "projectId": "my-project",
  "todos": [...],
  "lastSync": "2025-10-04T06:00:00.000Z",
  "githubSynced": true
}

Sync Session Todos

PUT /api/todos/{projectId}/sync
Content-Type: application/json

Request Body:

{
  "sessionId": "session-123",
  "todos": [...]
}

Response (200 OK):

{
  "success": true,
  "projectId": "my-project",
  "sessionId": "session-123",
  "todos": [...],
  "totalTodos": 10,
  "added": 2,
  "updated": 3,
  "lastSync": "2025-10-04T06:00:00.000Z"
}

AI Gateway

Base URL: https://ai.chitty.cc

OpenAI-compatible API powered by Cloudflare Workers AI.

Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "AI Gateway",
  "models": {
    "primary": "@cf/meta/llama-3.1-8b-instruct",
    "embedding": "@cf/baai/bge-base-en-v1.5"
  },
  "timestamp": "2025-10-04T06:00:00.000Z"
}

Chat Completions

POST /v1/chat/completions
Content-Type: application/json

Request Body:

{
  "model": "@cf/meta/llama-3.1-8b-instruct",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is ChittyOS?"}
  ],
  "max_tokens": 256,
  "temperature": 0.7
}

Response (200 OK):

{
  "id": "chatcmpl-1699999999",
  "object": "chat.completion",
  "created": 1699999999,
  "model": "@cf/meta/llama-3.1-8b-instruct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "ChittyOS is a comprehensive platform..."
      },
      "finish_reason": "stop"
    }
  ]
}

Embeddings

POST /v1/embeddings
Content-Type: application/json

Request Body:

{
  "model": "@cf/baai/bge-base-en-v1.5",
  "input": ["Text to embed", "Another text"]
}

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1, 0.2, 0.3, ...],
      "index": 0
    },
    {
      "object": "embedding",
      "embedding": [0.4, 0.5, 0.6, ...],
      "index": 1
    }
  ],
  "model": "@cf/baai/bge-base-en-v1.5",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

List Models

GET /v1/models

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "@cf/meta/llama-3.1-8b-instruct",
      "object": "model",
      "created": 1677610602,
      "owned_by": "cloudflare"
    },
    {
      "id": "@cf/baai/bge-base-en-v1.5",
      "object": "model",
      "created": 1677610602,
      "owned_by": "cloudflare"
    }
  ]
}

MCP Portal

Base URLs:

https://mcp.chitty.cc
https://portal.chitty.cc (alias)

Model Context Protocol service for AI assistant integration.

Endpoints

Health Check

GET /health

Response:

{
  "service": "mcp",
  "status": "healthy"
}

Error Codes

Standard HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication required or failed
404	Not Found	Resource not found
405	Method Not Allowed	HTTP method not supported
500	Internal Server Error	Server error occurred
501	Not Implemented	Endpoint not available in current environment
502	Bad Gateway	Upstream service unavailable

Service-Specific Errors

ChittyID Service

Pipeline Error: ChittyID service unavailable (502)
Validation Error: Invalid ChittyID format (200, valid: false)
Metadata Not Found: No metadata for ChittyID (404)

Auth Service

Token Required: Missing ChittyID in token request (400)
Invalid Token: Token verification failed (401)
Expired Token: Token has expired (401)

Sync Service

Project Not Found: Project doesn't exist (404)
Session Not Found: Session doesn't exist (404)
Method Not Allowed: Unsupported HTTP method (405)
Local Sync Unavailable: Requires Node.js runtime (501)

Rate Limits

Currently, no rate limits are enforced on ChittyOS platform services. However, Cloudflare Workers have the following limits:

CPU Time: 50ms per request (Bundled plan)
Memory: 128MB per request
Request Size: 100MB max
Response Size: No limit

For production use, consider implementing:

API key-based rate limiting
Per-session request throttling
Service-specific quotas

Examples

Complete Authentication Flow

# 1. Create auth token
curl -X POST https://auth.chitty.cc/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "chittyId": "01-P-EO-0001-T-25-C-X",
    "permissions": ["read", "write"],
    "expiresIn": 3600
  }'

# Response: {"access_token": "eyJ...", "token_type": "Bearer", ...}

# 2. Verify token
curl -X POST https://auth.chitty.cc/api/auth/verify \
  -H "Authorization: Bearer eyJ..."

# 3. Use token for protected resource
curl https://api.chitty.cc/api/project \
  -H "Authorization: Bearer eyJ..."

# 4. Refresh token before expiry
curl -X POST https://auth.chitty.cc/api/auth/refresh \
  -H "Authorization: Bearer eyJ..."

Project Sync Workflow

# 1. Register session
curl -X POST https://api.chitty.cc/api/session \
  -H "Content-Type: application/json" \
  -d '{
    "id": "session-abc123",
    "projectId": "my-app",
    "aiPlatform": "claude",
    "machineId": "mac-456"
  }'

# 2. Create/sync project
curl -X POST https://api.chitty.cc/api/project \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-app",
    "name": "My Application"
  }'

# 3. Sync session todos
curl -X PUT https://api.chitty.cc/api/todos/my-app/sync \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-abc123",
    "todos": [
      {
        "content": "Fix login bug",
        "status": "in_progress",
        "activeForm": "Fixing login bug"
      }
    ]
  }'

# 4. Get unified todos
curl https://api.chitty.cc/api/todos/my-app

# 5. End session
curl -X DELETE https://api.chitty.cc/api/session/session-abc123

AI Gateway Usage

# Chat completion
curl -X POST https://ai.chitty.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@cf/meta/llama-3.1-8b-instruct",
    "messages": [
      {"role": "user", "content": "Explain ChittyOS"}
    ],
    "max_tokens": 256
  }'

# Generate embeddings
curl -X POST https://ai.chitty.cc/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@cf/baai/bge-base-en-v1.5",
    "input": "ChittyOS platform documentation"
  }'

ChittyID Generation

# Generate ChittyID (requires API key)
curl -X POST https://id.chitty.cc/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "entityType": "PROP",
      "description": "User property record"
    },
    "sessionContext": {
      "sessionId": "session-123",
      "project": "my-app"
    }
  }'

# Validate ChittyID
curl https://id.chitty.cc/validate/01-P-ROP-0001-T-25-C-X

# Get metadata
curl https://id.chitty.cc/metadata/01-P-ROP-0001-T-25-C-X

Support

Documentation: See service-specific /health endpoints
Status: https://sync.chitty.cc/api/status
Platform Health: https://gateway.chitty.cc/health
Worker Logs: wrangler tail chittyos-platform-production --env production

Last Updated: 2025-10-04 Worker Version: 8814a03c-a4d8-43bb-a3a1-1643c3efaa0d

FilesExpand file tree

API-DOCUMENTATION.md

Latest commit

History

API-DOCUMENTATION.md

File metadata and controls

ChittyOS Platform API Documentation

Table of Contents

ChittyID Service

Endpoints

Health Check

Generate ChittyID

Validate ChittyID

Get ChittyID Metadata

Authentication Service

Endpoints

Health Check

Create Token

Verify Token

Refresh Token

Revoke Session

Sync Service

Architecture

Core Endpoints

Health Check

Overall Status

Project API

List Projects

Get Project

Create/Sync Project

Update Project

Delete Project

Session API

List Sessions

Get Session

Register Session

Update Session (Heartbeat)

End Session

Topic API

List Topics

Get Topic Conversations

Categorize Conversation

Todos API

List Projects with Todos

Get Unified Todos

Update Unified Todos

Sync Session Todos

AI Gateway

Endpoints

Health Check

Chat Completions

Embeddings

List Models

MCP Portal

Endpoints

Health Check

Error Codes

Standard HTTP Status Codes

Service-Specific Errors

ChittyID Service

Auth Service

Sync Service

Rate Limits

Examples

Complete Authentication Flow

Project Sync Workflow

AI Gateway Usage

ChittyID Generation

Support