Documentation

Developer documentation and API reference for building with Yohanun

Login Start Building
Getting Started
Core Features
API Reference
Resources

Welcome to Yohanun

Yohanun is a semantic runtime that gives your applications persistent memory, automated reasoning, and contextual intelligence. While others build chatbots, you'll build genuinely intelligent applications.

The Yohanun Difference

Rules + Memory = Experience. Yohanun doesn't just store data—it understands context, remembers relationships, and spots patterns that make your applications feel like they "just get it."

Quick Start

Get your first intelligent application running in under 5 minutes:

1. Get Your API Key
  1. Register for a developer account
  2. Generate an API key in your dashboard
  3. Note your API key for use in requests:
X-API-Key: sile_nidgbNEmjc9zmPx6lo9VLwTKGR9qHmuPgphMpeh3ltQ
Pro Tip: Your API key includes intelligent rate limiting and cost controls built-in.
2. Make Your First AI Chat Request
curl -X POST http://localhost:8000/api/ai/chat \ -H "X-API-Key: sile_nidgbNEmjc9zmPx6lo9VLwTKGR9qHmuPgphMpeh3ltQ" \ -H "Content-Type: application/json" \ -d '{ "message": "I'm frustrated with the slow response from your app", "context": { "user_id": "alice", "session_id": "session_123" } }'

What the API automatically provides:

  • 🤖
    Intelligent Response: AI-powered conversational responses
  • 🎯
    Intent Detection: Automatically categorizes user intent
  • 🧠
    Memory Storage: Stores conversation context for future use
  • ⚙️
    Model Selection: Uses best available AI model for the task

Authentication

All API requests require authentication using your API key in the request header:

X-API-Key: yohanun_your_api_key_here
Secure by Design

API keys use SHA-256 hashing and include automatic rate limiting, cost controls, and usage tracking.

Multi-App Support

Create separate API keys for different applications with isolated contexts and independent usage tracking.

Keep your API key secure! Never expose it in client-side code or public repositories.

Intelligent Processing

Yohanun's intelligent processing capabilities go beyond simple AI responses to provide context-aware, memory-enhanced, and temporally intelligent interactions.

Processing Features
🎯 Intent Detection: Automatically categorizes user intent
🔍 Entity Extraction: Identifies key entities and values
🧠 Context Awareness: Maintains conversation context
⏰ Temporal Intelligence: Time-aware memory retrieval

Intent Detection

Every message is automatically analyzed to determine user intent, enabling appropriate responses and triggering relevant automations.

Common Intents

Information Requests

Questions, queries, help requests

Task Execution

Commands, actions, operations

Support Issues

Problems, complaints, escalations

Example Response

{ "intent": "support_request", "entities": { "issue_type": "billing", "urgency": "high", "department": "accounting" }, "confidence": 0.92, "processing_time_ms": 45 }

Entity Extraction

Automatically identifies and extracts relevant entities from user messages including dates, names, locations, products, and custom business entities.

Entity Type Examples Use Cases
PERSON John Smith, Alice Cooper User identification, personalization
DATE_TIME tomorrow, next week, 3pm Scheduling, reminders
PRODUCT Pro Plan, API Credits Sales, support routing
LOCATION New York, Europe, Building A Routing, localization

Context Awareness

Yohanun maintains rich context throughout conversations, understanding references, follow-up questions, and conversational flow.

Context Types

  • 💬
    Conversational Context: Previous messages, topics discussed, references
  • 👤
    User Context: Preferences, history, profile information
  • 🏢
    Application Context: Business rules, workflows, current state
  • ⏰
    Temporal Context: Time-based relevance, session boundaries

Temporal Intelligence

Advanced time-aware processing that understands "this morning", "earlier today", "last week" and automatically boosts relevant memories based on temporal proximity.

Example: Thread Reactivation

When resuming a conversation after 2 days, Yohanun automatically detects the gap, retrieves relevant context from that timeframe, and provides seamless continuity.

Temporal Features

Memory Decay

Older memories naturally fade while recent interactions remain highly relevant

Session Boundaries

Automatic detection of conversation starts/stops for better context management

Time References

Natural language time processing: "this morning", "last Tuesday", "an hour ago"

Relevance Boosting

Recently discussed topics receive higher relevance scores in memory search

Real-Time WebSocket API

The Yohanun WebSocket API provides real-time streaming AI chat with live processing visibility, bidirectional communication, and enterprise-grade scaling. Experience word-by-word AI responses and instant feedback.

WebSocket Features
🚀 Real-Time Streaming: Word-by-word AI response generation
📊 Live Processing: Memory search and rule detection updates
⚡ Enterprise Scale: 1000+ connections per container
🔗 Container-Aware: Redis-coordinated load balancing

WebSocket Endpoints

WS /ws/chat Main WebSocket chat endpoint

Full AI integration with streaming responses and live processing updates

GET /ws/chat/test Interactive test page

Browser-based WebSocket testing and debugging interface

GET /ws/chat/stats Connection statistics

Real-time connection monitoring and health metrics

Quick Start

1. Connect and Authenticate

const websocket = new WebSocket('ws://localhost:8000/ws/chat'); websocket.onopen = function() { // Send authentication on connection websocket.send(JSON.stringify({ type: 'auth', api_key: 'sile_your_api_key_here', user_id: 'user_123', metadata: { source: 'my_app' } })); };

2. Send Chat Messages

// Send chat message with full context websocket.send(JSON.stringify({ type: 'chat_message', data: { message: "What did we discuss about the Q4 budget?", model: "claude-3-haiku-20240307" }, metadata: { thread_id: "thread_123", user_id: "user_456" } }));

3. Handle Real-Time Responses

websocket.onmessage = function(event) { const message = JSON.parse(event.data); switch(message.type) { case 'auth_success': console.log('✅ Authenticated:', message.client_id); break; case 'memory_search_progress': updateProgress('Memory search', message.progress); break; case 'chat_response_chunk': appendToResponse(message.content); break; case 'chat_response_complete': console.log('✅ Response complete'); break; } };

Message Types Reference

Client → Server Messages

Authentication
{ "type": "auth", "api_key": "sile_your_api_key", "user_id": "optional_user_id", "session_id": "optional_session_id", "metadata": {} }
Chat Message
{ "type": "chat_message", "data": { "message": "Your message here", "model": "claude-3-haiku-20240307", "memory_context": ["optional", "context", "ids"] }, "metadata": { "thread_id": "thread_123", "user_id": "user_456" } }
Control Messages
// Stop AI generation { "type": "stop_generation", "processing_id": "uuid" } // Heartbeat response { "type": "heartbeat_response" } // Simple ping { "type": "ping" }

Server → Client Messages

Authentication Response
{ "type": "auth_success", "client_id": "uuid", "developer_id": "uuid", "plan_tier": "developer", "selected_model": "claude-3-haiku-20240307" }
Live Processing Updates
// Memory search progress { "type": "memory_search_progress", "message": "Searching vector embeddings...", "progress": 0.3, "timestamp": "2025-01-04T14:00:00Z" } // Rule detection status { "type": "rule_detection_status", "status": "scanning", "message": "Scanning for automation rules..." } // AI processing status { "type": "ai_processing_status", "status": "generating", "model": "claude-3-haiku-20240307", "message": "Generating response..." }
Streaming AI Response
// Response chunk (word-by-word) { "type": "chat_response_chunk", "content": "Based on our", "chunk_index": 0, "total_chunks": 50, "timestamp": "2025-01-04T14:00:03Z" } // Response complete { "type": "chat_response_complete", "response_metadata": { "model_used": "claude-3-haiku-20240307", "memories_found": 5, "rule_detection": {"rules_detected": 0}, "thread_id": "thread_123" } }

Rate Limiting & Performance

WebSocket Limits

  • Sustained Rate: 60 messages/minute
  • Burst Rate: 10 messages/10 seconds
  • Max Connections: 1000 per container
  • Heartbeat: 30-second intervals

Performance Features

  • Auto-scaling: Container-aware load balancing
  • Failover: Redis-coordinated redundancy
  • Monitoring: Real-time connection statistics
  • Health Checks: Automatic connection monitoring

Code Examples

Python WebSocket Client

import asyncio import websockets import json async def websocket_chat(): uri = "ws://localhost:8000/ws/chat" async with websockets.connect(uri) as websocket: # Authenticate await websocket.send(json.dumps({ "type": "auth", "api_key": "sile_your_api_key_here", "user_id": "test_user" })) # Wait for auth response response = await websocket.recv() print("Auth:", json.loads(response)) # Send chat message await websocket.send(json.dumps({ "type": "chat_message", "data": {"message": "Hello, how are you?"}, "metadata": {"user_id": "test_user"} })) # Receive streaming responses while True: response = await websocket.recv() message = json.loads(response) print(f"{message['type']}: {message}") if message['type'] == 'chat_response_complete': break # Run the client asyncio.run(websocket_chat())

Node.js WebSocket Client

const WebSocket = require('ws'); const ws = new WebSocket('ws://localhost:8000/ws/chat'); ws.on('open', function open() { // Authenticate ws.send(JSON.stringify({ type: 'auth', api_key: 'sile_your_api_key_here', user_id: 'test_user' })); }); ws.on('message', function message(data) { const msg = JSON.parse(data); switch(msg.type) { case 'auth_success': console.log('✅ Authenticated successfully'); // Send a chat message ws.send(JSON.stringify({ type: 'chat_message', data: { message: 'Tell me a joke' }, metadata: { user_id: 'test_user' } })); break; case 'chat_response_chunk': process.stdout.write(msg.content); break; case 'chat_response_complete': console.log('\n✅ Response complete'); ws.close(); break; } });

Testing & Monitoring

Interactive Testing

Use the built-in test page for interactive WebSocket testing:

http://localhost:8000/ws/chat/test

Connection Statistics

Monitor WebSocket connections and performance:

curl http://localhost:8000/ws/chat/stats # Response: { "status": "success", "stats": { "container_id": "9aff9a167ca9", "local_connections": 5, "max_connections": 1000, "utilization": "0.5%" }, "active_chat_sessions": 3 }

Error Handling Best Practices

  • Authentication Timeout: Authenticate within 10 seconds of connection
  • Rate Limiting: Handle rate limit responses gracefully with exponential backoff
  • Connection Loss: Implement reconnection logic with jitter to prevent thundering herd
  • Message Validation: Always validate message structure before sending

AI Runtime API

The core AI Runtime API provides intelligent conversation capabilities with advanced features including intent detection, temporal memory integration, rule management, and multi-model support.

AI Runtime Features
🧠 Intelligent Processing: Context-aware AI responses
🎯 Intent Detection: Automatic intent and entity extraction
📚 Memory Integration: Persistent context across sessions
⚙️ Rule Management: Automated rule creation and execution
POST /api/ai/chat Primary AI chat endpoint

Intelligent Chat Processing

The main AI endpoint that processes messages with full context, memory integration, and intelligent response generation.

Request Format

{ "message": "What did we discuss about the Q4 budget?", "context": { "user_id": "alice", "department": "finance" }, "model": "claude-3-haiku-20240307", "system_prompt": "You are a helpful financial assistant", "thread_id": "thread_abc123", "session_id": "session_456", "user_id": "user_123", "memory_context": ["app_name", "knowledge_base", "private:user_123"] }

Request Parameters

Parameter Type Required Description
message string ✅ Yes The user's message to process
context object No Additional context for processing
model string No AI model to use (overrides app default)
system_prompt string No Custom system instructions
thread_id string No Conversation thread identifier
session_id string No Session within thread
user_id string No User identifier for isolation
memory_context array No Memory search contexts

Response Format

{ "response": "Based on our previous discussions, the Q4 budget allocation focuses on...", "intent": "information_request", "entities": { "topic": "budget", "time_period": "Q4" }, "generated_at": "2025-01-04T14:30:00Z", "model_used": "claude-3-haiku-20240307", "rule_detection": { "rules_detected": 0, "potential_rules": [] }, "temporal_context": { "thread_reactivation": { "is_reactivation": true, "dormancy_hours": 48, "last_activity": "2025-01-02T14:30:00Z" }, "memories_found": 5, "temporal_boosts_applied": 2 } }

Response Fields

Field Type Description
response string Generated AI response
intent string Detected user intent
entities object Extracted entities from message
model_used string Actual AI model used
rule_detection object Rule creation opportunities
temporal_context object Thread reactivation and memory info
POST /api/ai/chat-stream Streaming AI chat endpoint

Server-Sent Events (SSE) Streaming

Identical to the regular chat endpoint but returns streaming responses using Server-Sent Events. Perfect for real-time applications without WebSocket complexity.

Request Format

curl -X POST http://localhost:8000/api/ai/chat-stream \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{ "message": "Tell me about quantum computing", "model": "claude-3-haiku-20240307", "thread_id": "thread_123" }'

Streaming Response

event: start data: {"model": "claude-3-haiku-20240307"} event: memory_search data: {"status": "searching", "progress": 0.3} event: chunk data: {"content": "Quantum computing is a revolutionary", "index": 0} event: chunk data: {"content": " technology that leverages", "index": 1} event: complete data: {"model_used": "claude-3-haiku-20240307", "total_tokens": 150}
POST /api/ai/detect-intent Intent detection only

Intent Detection

Extract intent and entities from user messages without generating a response. Useful for routing and classification tasks.

curl -X POST http://localhost:8000/api/ai/detect-intent \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "message": "I need to cancel my subscription", "context": {"user_id": "alice"} }'

Response

{ "intent": "cancel_subscription", "entities": { "action": "cancel", "service": "subscription" }, "confidence": 0.95, "context": {"user_id": "alice"} }
POST /api/ai/generate-response Response generation

Response Generation

Generate natural language responses based on detected intent and entities. Useful for building custom conversation flows.

curl -X POST http://localhost:8000/api/ai/generate-response \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "intent": "cancel_subscription", "entities": {"action": "cancel", "service": "subscription"}, "context": {"user_id": "alice", "plan": "premium"} }'

Response

{ "response": "I understand you'd like to cancel your premium subscription. I can help you with that...", "generated_at": "2025-01-04T14:30:00Z" }

Thread Management API

Manage conversation threads for persistent, contextual interactions. Threads maintain conversation history and enable temporal memory features.

POST /api/threads/ Create new thread

Create Thread

curl -X POST http://localhost:8000/api/threads/ \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "title": "Customer Support Session", "user_id": "user_123", "thread_type": "conversation", "metadata": {"department": "support"} }'

Response

{ "thread_id": "thread_abc123", "title": "Customer Support Session", "user_id": "user_123", "thread_type": "conversation", "created_at": "2025-01-04T14:30:00Z", "metadata": {"department": "support"} }
GET /api/threads/{thread_id}/messages Get thread history

Retrieve Thread Messages

curl -X GET http://localhost:8000/api/threads/thread_abc123/messages \ -H "X-API-Key: sile_your_api_key" \ -G -d "limit=50" -d "offset=0"

Response

{ "messages": [ { "message_id": "msg_123", "content": "Hello, I need help with my account", "message_type": "user", "timestamp": "2025-01-04T14:30:00Z", "user_id": "user_123" }, { "message_id": "msg_124", "content": "I'd be happy to help you with your account...", "message_type": "assistant", "timestamp": "2025-01-04T14:30:05Z", "model_used": "claude-3-haiku-20240307" } ], "total": 2, "thread_id": "thread_abc123" }
GET /api/threads/ List user threads

List Threads

curl -X GET http://localhost:8000/api/threads/ \ -H "X-API-Key: sile_your_api_key" \ -G -d "user_id=user_123" -d "limit=20"

Response

{ "threads": [ { "thread_id": "thread_abc123", "title": "Customer Support Session", "user_id": "user_123", "thread_type": "conversation", "created_at": "2025-01-04T14:30:00Z", "last_activity": "2025-01-04T15:45:00Z", "message_count": 8 } ], "total": 1 }

Persistent Memory System

Yohanun's memory system stores and retrieves contextual information across sessions, building understanding that makes your applications genuinely intelligent.

POST /api/memory/store Store contextual memory

Store Contextual Memory

Store information that builds understanding over time. Memories are automatically embedded and indexed for semantic search.

curl -X POST http://localhost:8000/api/memory/store \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "content": "User Alice prefers morning meetings and uses iPhone", "contexts": ["app_name", "user_preferences", "private:alice"], "metadata": { "category": "preferences", "importance": "high", "source": "conversation" } }'

Response

{ "memory_id": "mem_abc123", "content": "User Alice prefers morning meetings and uses iPhone", "contexts": ["app_name", "user_preferences", "private:alice"], "created_at": "2025-01-04T14:30:00Z", "embedding_status": "complete" }
POST /api/memory/search Search memories

Search Memory

Semantic search across stored memories with context filtering and relevance scoring.

curl -X POST http://localhost:8000/api/memory/search \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "query": "Alice meeting preferences", "contexts": ["app_name", "user_preferences"], "limit": 5, "min_relevance": 0.7 }'

Response

{ "query": "Alice meeting preferences", "results": [ { "memory_id": "mem_abc123", "content": "User Alice prefers morning meetings and uses iPhone", "contexts": ["app_name", "user_preferences", "private:alice"], "relevance_score": 0.92, "created_at": "2025-01-04T14:30:00Z", "metadata": {"category": "preferences"} } ], "total": 1 }
GET /api/memory/stats Memory statistics

Memory Statistics

curl -X GET http://localhost:8000/api/memory/stats \ -H "X-API-Key: sile_your_api_key"

Response

{ "total_memories": 1250, "contexts": { "app_name": 450, "user_preferences": 200, "knowledge_base": 600 }, "storage_usage": { "vector_embeddings": "2.3GB", "metadata": "145MB" }, "recent_activity": { "memories_created_today": 23, "searches_today": 156 } }

Rules Engine API

Create and manage intelligent automation rules that trigger actions based on conversation patterns, user behavior, and contextual conditions.

POST /api/ai/create-rule Create automation rule

Create Rule

Create intelligent automation rules using natural language. The AI analyzes your instruction and creates appropriate triggers and actions.

curl -X POST http://localhost:8000/api/ai/create-rule \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "instruction": "When users mention urgent support issues, escalate to senior support within 5 minutes", "category": "support_escalation", "priority": "high" }'

Response

{ "rule_id": "rule_abc123", "instruction": "When users mention urgent support issues, escalate to senior support within 5 minutes", "status": "active", "triggers": [ { "type": "intent_match", "condition": "urgent_support_request", "confidence_threshold": 0.8 } ], "actions": [ { "type": "escalate", "target": "senior_support", "delay_minutes": 5 } ], "created_at": "2025-01-04T14:30:00Z" }
GET /api/rules/ List all rules

List Rules

curl -X GET http://localhost:8000/api/rules/ \ -H "X-API-Key: sile_your_api_key" \ -G -d "status=active" -d "limit=20"

Response

{ "rules": [ { "rule_id": "rule_abc123", "instruction": "When users mention urgent support issues, escalate to senior support within 5 minutes", "status": "active", "category": "support_escalation", "priority": "high", "created_at": "2025-01-04T14:30:00Z", "last_triggered": "2025-01-04T16:15:00Z", "trigger_count": 12 } ], "total": 1 }

Database Service API

Managed database instances optimized for AI workloads with automated backups, monitoring, and scaling. Deploy PostgreSQL instances with vector search capabilities.

Database Features
🚀 AI-Optimized: Vector extensions and AI-specific configurations
🔄 Automated Backups: Daily backups with point-in-time recovery
📊 Real-time Metrics: Performance monitoring and alerting
⚡ Multi-size Plans: From development to production workloads
POST /api/database-service/instances Create database instance

Create Database Instance

Deploy a managed PostgreSQL instance with AI optimizations and automated configuration.

Request Format

curl -X POST http://localhost:8000/api/database-service/instances \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "my-ai-database", "type": "postgresql", "template": "ai_optimized", "size": "small", "region": "us-east-1", "backup_enabled": true }'

Response

{ "instance_id": "db_abc123", "name": "my-ai-database", "type": "postgresql", "status": "creating", "connection_string": "postgresql://user:pass@host:5432/dbname", "host": "ai-db-abc123.yohanun.ai", "port": 5432, "database_name": "aidb_abc123", "username": "aiuser_abc123", "size": "small", "created_at": "2025-01-04T14:30:00Z", "ai_optimizations": { "extensions": ["pgvector", "pg_trgm", "btree_gin"], "config": {"shared_buffers": "256MB", "work_mem": "16MB"} } }
GET /api/database-service/instances List database instances

List Database Instances

curl -X GET http://localhost:8000/api/database-service/instances \ -H "X-API-Key: sile_your_api_key"

Response

[ { "instance_id": "db_abc123", "name": "my-ai-database", "type": "postgresql", "status": "ready", "connection_string": "postgresql://user:***@host:5432/dbname", "host": "ai-db-abc123.yohanun.ai", "port": 5432, "database_name": "aidb_abc123", "username": "aiuser_abc123", "size": "small", "created_at": "2025-01-04T14:30:00Z" } ]
GET /api/database-service/instances/{instance_id}/metrics Get performance metrics

Database Metrics

Real-time performance metrics including CPU, memory, storage, and AI-specific query performance.

curl -X GET http://localhost:8000/api/database-service/instances/db_abc123/metrics \ -H "X-API-Key: sile_your_api_key"

Response

{ "cpu_usage": 15.5, "memory_usage": 45.2, "storage_used_gb": 2.1, "storage_total_gb": 10.0, "connections_active": 3, "connections_max": 100, "queries_per_second": 12.4, "ai_query_performance": { "avg_vector_query_ms": 45, "avg_similarity_search_ms": 32, "index_efficiency": 0.94 } }
GET /api/database-service/templates Get database templates

Database Templates

Pre-configured database templates optimized for different use cases.

AI Optimized

Vector search, similarity matching, AI workloads

  • • pgvector extension
  • • pg_trgm for text search
  • • Optimized for embeddings

Analytics

Reporting, aggregations, time-series data

  • • pg_stat_statements
  • • pg_partman for partitioning
  • • Enhanced query performance

Basic

General purpose applications

  • • uuid-ossp extension
  • • Standard PostgreSQL
  • • Cost-effective option

Backup Management

Create Manual Backup

POST /api/database-service/instances/{id}/backup { "backup_name": "Pre-migration backup" }

List Backups

GET /api/database-service/instances/{id}/backups ?backup_type=manual&limit=10
Automated Backups

All database instances include automated daily backups with 30-day retention. Point-in-time recovery available for the last 7 days.

Storage Management API

Monitor and manage storage usage across all databases (PostgreSQL, Neo4j, Qdrant, Redis) with automated tracking, cleanup recommendations, and usage analytics.

GET /api/storage/usage Get storage usage

Storage Usage

Get current storage usage across all databases with breakdown by system.

curl -X GET http://localhost:8000/api/storage/usage \ -H "X-API-Key: sile_your_api_key" \ -G -d "force_refresh=true"

Response

{ "client_id": "client_abc123", "postgresql_mb": 245.7, "neo4j_mb": 156.2, "chromadb_mb": 89.1, "total_mb": 490.9, "total_gb": 0.48, "last_calculated": "2025-01-04T14:30:00Z" }
GET /api/storage/history Get storage history

Storage History

curl -X GET http://localhost:8000/api/storage/history \ -H "X-API-Key: sile_your_api_key" \ -G -d "days=30"

Response

[ { "date": "2025-01-04", "database": "postgresql", "storage_gb": 0.24, "metadata": {"tables": 12, "indexes": 8} }, { "date": "2025-01-04", "database": "neo4j", "storage_gb": 0.16, "metadata": {"nodes": 1542, "relationships": 3204} } ]
GET /api/storage/cleanup Get cleanup recommendations

Storage Cleanup

Get automated recommendations for storage optimization and cleanup.

curl -X GET http://localhost:8000/api/storage/cleanup \ -H "X-API-Key: sile_your_api_key"

Response

{ "recommendations": [ { "type": "old_memories", "description": "Remove memories older than 1 year", "estimated_savings_mb": 45.2, "safety_level": "safe", "auto_cleanup_available": true }, { "type": "unused_embeddings", "description": "Remove orphaned vector embeddings", "estimated_savings_mb": 12.7, "safety_level": "safe", "auto_cleanup_available": true } ], "total_potential_savings_mb": 57.9, "cleanup_status": "recommendations_available" }

Execute Cleanup

curl -X POST http://localhost:8000/api/storage/cleanup \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "cleanup_types": ["old_memories", "unused_embeddings"], "confirm": true }'

Response

{ "cleanup_id": "cleanup_abc123", "status": "in_progress", "estimated_duration_minutes": 5, "cleanup_types": ["old_memories", "unused_embeddings"], "started_at": "2025-01-04T14:30:00Z" }

Error Handling

Understand standard error responses and implement robust error handling in your applications.

Standard Error Format

All API errors follow a consistent format with HTTP status codes and detailed error information.

{ "error": { "code": "AUTHENTICATION_FAILED", "message": "Invalid API key provided", "details": "The API key 'sile_invalid_key' is not valid or has been revoked", "suggestion": "Check your API key in the developer dashboard" }, "request_id": "req_abc123", "timestamp": "2025-01-04T14:30:00Z" }

Common Error Codes

HTTP Status Error Code Description
400 INVALID_REQUEST Missing required parameters or invalid format
401 AUTHENTICATION_FAILED Invalid or missing API key
403 INSUFFICIENT_PERMISSIONS API key lacks required permissions
429 RATE_LIMIT_EXCEEDED Too many requests - rate limit exceeded
500 INTERNAL_SERVER_ERROR Unexpected server error

Error Handling Best Practices

  • Implement Retry Logic: Use exponential backoff for rate limits and temporary failures
  • Log Request IDs: Include request_id in error logs for debugging
  • Handle Gracefully: Show user-friendly messages while logging technical details
  • Monitor Error Rates: Track error patterns to identify systemic issues

Integration Guide

Get started integrating Yohanun into your applications using direct API calls or our code examples.

REST API Integration

The Yohanun platform uses standard REST APIs that work with any HTTP client in any programming language.

Python Example

import requests # Send chat message response = requests.post( "http://localhost:8000/api/ai/chat", headers={ "X-API-Key": "sile_your_api_key", "Content-Type": "application/json" }, json={ "message": "Hello, how are you?", "thread_id": "thread_123" } ) data = response.json() print(f"AI: {data['response']}")

JavaScript Example

// Send chat message const response = await fetch( "http://localhost:8000/api/ai/chat", { method: "POST", headers: { "X-API-Key": "sile_your_api_key", "Content-Type": "application/json" }, body: JSON.stringify({ message: "Hello, how are you?", thread_id: "thread_123" }) } ); const data = await response.json(); console.log(`AI: ${data.response}`);

WebSocket Integration

For real-time applications, use our WebSocket API for streaming responses.

// Connect to WebSocket const ws = new WebSocket('ws://localhost:8000/ws/chat'); ws.onopen = () => { // Authenticate ws.send(JSON.stringify({ type: 'auth', api_key: 'sile_your_api_key', user_id: 'user_123' })); }; ws.onmessage = (event) => { const message = JSON.parse(event.data); if (message.type === 'chat_response_chunk') { console.log('Chunk:', message.content); } }; // Send message after authentication setTimeout(() => { ws.send(JSON.stringify({ type: 'chat_message', data: { message: 'Hello!' } })); }, 1000);

SDK Development

Official SDKs Coming Soon

We're currently developing official SDKs for Python, JavaScript, and other popular languages. In the meantime, the REST and WebSocket APIs provide full functionality for any HTTP client.

Interested in contributing? Contact us about SDK development opportunities.

More Examples

Find comprehensive code examples throughout this documentation:

Document Processing API

Upload, process, and search documents with intelligent chunking, relationship mapping, and semantic understanding.

POST /api/documents/upload Upload document

Upload Document

Upload documents for intelligent processing with semantic chunking and relationship mapping.

curl -X POST http://localhost:8000/api/documents/upload \ -H "X-API-Key: sile_your_api_key" \ -F "file=@document.pdf" \ -F "chunking_strategy=semantic_sections" \ -F "create_relationships=true" \ -F "contexts=knowledge_base,policies"

Response

{ "document_id": "doc_abc123", "filename": "document.pdf", "status": "processing", "chunking_strategy": "semantic_sections", "estimated_chunks": 25, "processing_started": "2025-01-04T14:30:00Z" }
POST /api/documents/search Search documents

Search Documents

curl -X POST http://localhost:8000/api/documents/search \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "query": "employee vacation policy", "filters": { "contexts": ["knowledge_base", "policies"] }, "include_chunks": true, "limit": 10 }'

Response

{ "results": [ { "document_id": "doc_abc123", "filename": "employee_handbook.pdf", "chunks": [ { "chunk_id": "chunk_def456", "content": "Employee vacation policy allows for 15 days...", "page_number": 12, "relevance_score": 0.94 } ], "contexts": ["knowledge_base", "policies"] } ], "total": 1 }
GET /api/documents/ List documents

List Documents

curl -X GET http://localhost:8000/api/documents/ \ -H "X-API-Key: sile_your_api_key" \ -G -d "status=processed" -d "limit=20"

Response

{ "documents": [ { "document_id": "doc_abc123", "filename": "employee_handbook.pdf", "status": "processed", "upload_date": "2025-01-04T14:30:00Z", "chunk_count": 25, "contexts": ["knowledge_base", "policies"] } ], "total": 1 }

Support & Resources

Documentation

Complete API reference and architecture guides

View Code Examples →
Support

Get help with integration and troubleshooting

Contact Support →

Troubleshooting

Common issues and solutions to help you debug and resolve problems quickly.

Common Issues

Authentication Failed

Error: "Valid API key required for this endpoint"

Solutions:
  • Check your API key format: should start with "sile_"
  • Ensure API key is in the X-API-Key header
  • Verify your API key is active in the developer dashboard
  • Check for typos or extra spaces in the API key

Rate Limit Exceeded

Error: "Rate limit exceeded - too many requests"

Solutions:
  • Implement exponential backoff in your retry logic
  • Check the rate limit headers in the response
  • Consider upgrading your plan for higher limits
  • For WebSocket: max 60 msgs/min, 10 burst/10sec

WebSocket Connection Issues

Error: Connection drops or authentication timeout

Solutions:
  • Authenticate within 10 seconds of connecting
  • Implement reconnection logic with jitter
  • Handle heartbeat messages properly
  • Check WebSocket URL format: ws://localhost:8000/ws/chat

Memory Search Returns No Results

Issue: Memory search returns empty results

Solutions:
  • Check if memories are stored with correct contexts
  • Verify memory_context array in your requests
  • Allow time for embedding processing to complete
  • Try broader search terms or lower relevance threshold

Debug Steps

1. Check API Health

curl -X GET http://localhost:8000/health # Expected response: { "status": "ok", "version": "0.1.0", "system": "memory_system" }

2. Test WebSocket Statistics

curl -X GET http://localhost:8000/ws/chat/stats # Check connection capacity and health

3. Verify API Key Format

# Valid API key format: X-API-Key: sile_nidgbNEmjc9zmPx6lo9VLwTKGR9qHmuPgphMpeh3ltQ # Check length: should be 51 characters (sile_ + 46 characters)

4. Test Basic Chat Request

curl -X POST http://localhost:8000/api/ai/chat \ -H "X-API-Key: your_api_key" \ -H "Content-Type: application/json" \ -d '{"message": "Hello, this is a test"}'

Performance Tips

Memory Context Optimization

  • • Use specific context arrays to limit search scope
  • • Implement user-specific contexts: "private:user_123"
  • • Consider temporal search for conversation references
  • • Limit memory results to 10-15 for best performance

Thread Management

  • • Create threads once and reuse them
  • • Use thread_id for automatic message storage
  • • Implement thread cleanup for long-running sessions
  • • Consider session_id for sub-conversations

Getting Help

If you're still experiencing issues after trying these troubleshooting steps:

  • • Include your request_id from error responses
  • • Provide the exact error message and HTTP status code
  • • Share the minimal code that reproduces the issue
  • • Check the code examples for reference implementations