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:

Using Claude Code? The fastest route is Yohanun Guilds — persistent, access-governed memory for your coding agents; one copy-paste prompt and your agent sets itself up.

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: YOUR_API_KEY
Pro Tip: Your API key includes intelligent rate limiting and cost controls built-in.
2. Make Your First Request

Memory app (the default — your AI, our memory): store something, then find it again by meaning:

curl -X POST https://app.yohanun.com/api/memory/memories \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "Alice prefers async standups over meetings", "context": "team-preferences", "user_id": "alice" }' curl -X POST https://app.yohanun.com/api/memory/search \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "how does alice like to run standups", "user_id": "alice" }'

Chat app (Yohanun runs the model — needs a chat-type key, see app types):

curl -X POST https://app.yohanun.com/api/ai/chat \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "What does Alice prefer for standups?", "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: sile_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.

App types: what your key can call

Every app (and its key) has a type, chosen when you create it under Applications. The type decides which parts of the API the key can reach — enforced before any request is processed.

Memory app (bring your own AI)

The memory & governance surface: /api/memory, /api/threads, /api/documents*, /api/learning, and the access-control reads. Your own model does the talking; Yohanun remembers and enforces.

Not included: /api/ai/* and /api/agent/* — calls to them return 403 app type does not include this endpoint. This is the key the Guilds kit uses.

Chat app (Yohanun runs inference)

The full surface, including /api/ai/chat, streaming, WebSocket chat and the agent runtime — metered, or bring your own provider keys. Everything a memory app can call, plus the AI runtime sections below.

Examples in the AI Runtime, WebSocket and Rules sections below need a chat app key. Everything under Threads, Memory System and Documents works with either type.

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('wss://app.yohanun.com/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 = "wss://app.yohanun.com/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('wss://app.yohanun.com/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:

https://app.yohanun.com/ws/chat/test

Connection Statistics

Monitor WebSocket connections and performance:

curl https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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/memories 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 https://app.yohanun.com/api/memory/memories \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "content": "User Alice prefers morning meetings and uses iPhone", "context": "user_preferences", "tags": ["preferences", "alice"], "metadata": { "category": "preferences", "importance": "high", "source": "conversation" } }'

Response

{ "memory_id": "a1b2c3d4-...", "message": "Memory created successfully" }

Optional access labels on create: user_id (user-level isolation), acl_owners (personal memory — returns only to those principals), acl_matter + acl_classification (compartment and level 0–3, enforced by the read gate).

POST /api/memory/search Search memories

Search Memory

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

curl -X POST https://app.yohanun.com/api/memory/search \ -H "X-API-Key: sile_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "query": "Alice meeting preferences", "context": "user_preferences", "limit": 5, "user_id": "alice" }'

context (singular) filters to one context; omit it to search everything your key can see. Results run the full retrieval path — temporal decay, ranking, and the access gate — so relevance is already applied to the ordering; there is no min_relevance parameter.

Response

{ "results": [ { "memory_id": "a1b2c3d4-...", "content": "User Alice prefers morning meetings and uses iPhone", "context": "user_preferences", "relevance_score": 0.92, "created_at": "2026-07-04T14:30:00Z", "metadata": {"category": "preferences"} } ], "total": 1, "policy_effects": {}, "graph_context": {} }
GET /api/memory/stats Memory statistics

Memory Statistics

curl -X GET https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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 https://app.yohanun.com/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.com", "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 https://app.yohanun.com/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.com", "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 https://app.yohanun.com/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.

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( "https://app.yohanun.com/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( "https://app.yohanun.com/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('wss://app.yohanun.com/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-qdrant/upload Upload document

Upload Document

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

curl -X POST https://app.yohanun.com/api/documents-qdrant/upload \ -H "X-API-Key: sile_your_api_key" \ -F "file=@document.pdf" \ -F "user_id=alice" \ -F "chunking_strategy=semantic_sections" \ -F "create_relationships=true"

user_id is required. Optional access labels: matter (compartment, default public), classification (0–3), owners (comma-separated identities — makes it a personal document, visible only to those principals).

Response

{ "document_id": "doc_abc123", "filename": "document.pdf", "chunks_created": 25, "processing_time_ms": 1840.5, "status": "completed", "vector_ids": ["..."], "extraction_method": "pymupdf", "pages_processed": 12, "ocr_used": false, "password_protected": false, "graph_extraction": "scheduled" }
POST /api/documents-qdrant/search Search documents

Search Documents

curl -X POST https://app.yohanun.com/api/documents-qdrant/search \ -H "X-API-Key: sile_your_api_key" \ -F "query=employee vacation policy" \ -F "limit=10" \ -F "user_id=alice"

Form-encoded, not JSON. user_id is an optional ownership filter. Document chunks also surface automatically in /api/memory/search and chat memory context — this endpoint is for document-only search.

Response

{ "query": "employee vacation policy", "results_count": 1, "results": [ { "document_id": "doc_abc123", "filename": "employee_handbook.pdf", "content": "Employee vacation policy allows for 15 days...", "relevance_score": 0.94 } ] }
GET /api/documents/ List documents

List Documents

curl -X GET https://app.yohanun.com/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 }

Memory Lifecycle & Governance APIs

Memories are never edited or deleted — they are closed (retired from retrieval, still readable by id) or superseded (replaced by a successor that inherits context, tags and access labels unless overridden).

POST /api/memory/memories/{id}/close {"reason": "done|obsolete|error|junk"} POST /api/memory/memories/{id}/supersede {"content": "corrected text", ...}

Further platform surfaces (full reference in the interactive API docs):

  • /api/access/* — clearances, compartments, ownership keys, mandates & human escalations (the governance core)
  • /api/agreements/* — negotiated agreements between two principals, mandate-gated and co-signed
  • /api/agent/run — the bounded agent runtime over policied memory
  • /api/learning/outcome — report outcomes; lessons become retrievable and ranking adapts

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: wss://app.yohanun.com/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 https://app.yohanun.com/health # Expected response: { "status": "ok", "version": "0.1.0", "system": "memory_system" }

2. Test WebSocket Statistics

curl -X GET https://app.yohanun.com/ws/chat/stats # Check connection capacity and health

3. Verify API Key Format

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

4. Test Basic Chat Request

curl -X POST https://app.yohanun.com/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