API Reference

This document provides comprehensive API documentation for the Metacogna Subculture Management (MSM) System. The API follows RESTful principles and provides endpoints for all major system functionality.

Base URL

https://api.metacogna.com/v1

Authentication

All API requests require authentication using API keys or OAuth 2.0 tokens.

API Key Authentication

Authorization: Bearer YOUR_API_KEY

OAuth 2.0 Authentication

Authorization: Bearer YOUR_OAUTH_TOKEN

Rate Limiting

Standard Rate Limit: 1000 requests per hour per API key
Burst Limit: 100 requests per minute
Rate Limit Headers: Included in all responses

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid",
    "details": {
      "field": "user_id",
      "reason": "User ID is required"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
`INVALID_REQUEST`	400	Request validation failed
`UNAUTHORIZED`	401	Authentication required
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Rate limit exceeded
`INTERNAL_ERROR`	500	Internal server error

Core Endpoints

Cultural Analysis

Detect Subculture

Detect the subculture of a user based on their communication patterns and behavior.

POST /cultural-analysis/detect

Request Body:

{
  "user_id": "user_123",
  "communication_data": {
    "messages": [
      {
        "content": "We need to optimize the database queries for better performance",
        "timestamp": "2024-01-15T10:30:00Z",
        "context": "technical_discussion"
      }
    ],
    "interaction_patterns": {
      "decision_making_style": "analytical",
      "communication_preference": "technical",
      "collaboration_style": "structured"
    }
  }
}

Response:

{
  "subculture": {
    "id": "engineering",
    "name": "Engineering",
    "confidence": 0.87,
    "characteristics": {
      "values": ["technical_excellence", "quality", "precision"],
      "communication_style": "technical",
      "decision_making": "analytical"
    }
  },
  "analysis_metadata": {
    "analysis_time": "2024-01-15T10:31:00Z",
    "data_points_analyzed": 15,
    "model_version": "v2.1.0"
  }
}

Analyze Cultural Dynamics

Analyze the cultural dynamics between different subcultures in an organization.

POST /cultural-analysis/dynamics

Request Body:

{
  "organization_id": "org_456",
  "time_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "subcultures": ["engineering", "product", "marketing"]
}

Response:

{
  "cultural_dynamics": {
    "interaction_patterns": {
      "engineering_product": {
        "collaboration_score": 0.72,
        "conflict_frequency": 0.15,
        "communication_effectiveness": 0.68
      },
      "engineering_marketing": {
        "collaboration_score": 0.45,
        "conflict_frequency": 0.28,
        "communication_effectiveness": 0.52
      }
    },
    "alignment_metrics": {
      "overall_alignment": 0.62,
      "goal_alignment": 0.58,
      "process_alignment": 0.66
    }
  }
}

Cultural Translation

Translate Message

Translate a message between different subcultures.

POST /translation/translate

Request Body:

{
  "message": {
    "content": "We need to refactor the legacy codebase to improve maintainability and reduce technical debt",
    "source_subculture": "engineering",
    "target_subculture": "product"
  },
  "context": {
    "urgency": "medium",
    "stakeholders": ["product_manager", "engineering_lead"],
    "project_timeline": "3_months"
  }
}

Response:

{
  "translated_message": {
    "content": "We need to update our core systems to make them more reliable and easier to work with, which will help us deliver new features faster and with fewer issues",
    "confidence": 0.89,
    "preserved_intent": true
  },
  "translation_metadata": {
    "translation_time": "2024-01-15T10:32:00Z",
    "model_version": "v1.5.0",
    "cultural_adaptations": [
      "technical_to_business_language",
      "added_business_impact_context"
    ]
  }
}

Batch Translation

Translate multiple messages in a single request.

POST /translation/batch

Request Body:

{
  "messages": [
    {
      "id": "msg_1",
      "content": "The API response time is 2.3 seconds",
      "source_subculture": "engineering",
      "target_subculture": "product"
    },
    {
      "id": "msg_2",
      "content": "We need to increase our market share by 15%",
      "source_subculture": "product",
      "target_subculture": "engineering"
    }
  ]
}

Response:

{
  "translations": [
    {
      "id": "msg_1",
      "translated_content": "The system is responding slowly, which may impact user experience",
      "confidence": 0.92
    },
    {
      "id": "msg_2",
      "translated_content": "We need to build features that will help us capture more customers and grow our business",
      "confidence": 0.87
    }
  ]
}

Trust Management

Calculate Trust Score

Calculate the trust score between a user and the AI system.

POST /trust/calculate

Request Body:

{
  "user_id": "user_123",
  "context": {
    "interaction_type": "decision_support",
    "domain": "technical_architecture",
    "stakeholders": ["engineering_team", "product_team"]
  }
}

Response:

{
  "trust_score": {
    "overall": 0.78,
    "components": {
      "transparency": 0.82,
      "reliability": 0.75,
      "fairness": 0.80,
      "empathy": 0.76
    }
  },
  "trust_factors": {
    "positive": [
      "consistent_decision_quality",
      "clear_explanations",
      "fair_resource_allocation"
    ],
    "negative": [
      "occasional_uncertainty_issues",
      "limited_context_understanding"
    ]
  }
}

Update Trust Metrics

Update trust metrics based on user feedback.

POST /trust/update

Request Body:

{
  "user_id": "user_123",
  "interaction_id": "interaction_456",
  "feedback": {
    "satisfaction": 0.85,
    "explanation_quality": 0.90,
    "decision_accuracy": 0.80,
    "cultural_sensitivity": 0.75
  }
}

Response:

{
  "updated_trust_score": 0.79,
  "improvement_areas": [
    "cultural_sensitivity",
    "decision_accuracy"
  ]
}

Memory Management

Store Interaction

Store a human-AI interaction in the memory graph.

POST /memory/store

Request Body:

{
  "interaction": {
    "id": "interaction_789",
    "user_id": "user_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "type": "decision_support",
    "content": {
      "query": "Should we prioritize performance optimization or new feature development?",
      "context": {
        "project": "mobile_app",
        "timeline": "6_weeks",
        "resources": "limited"
      }
    },
    "outcome": {
      "decision": "prioritize_performance",
      "reasoning": "Performance issues are affecting user retention",
      "confidence": 0.85
    }
  }
}

Response:

{
  "stored": true,
  "memory_id": "memory_abc123",
  "storage_metadata": {
    "episodic_memory": true,
    "semantic_extraction": true,
    "procedural_pattern": true
  }
}

Retrieve Context

Retrieve relevant context for a user query.

POST /memory/retrieve

Request Body:

{
  "query": "What are the best practices for handling performance issues in mobile applications?",
  "user_id": "user_123",
  "context_type": "decision_support",
  "max_results": 10
}

Response:

{
  "context": [
    {
      "id": "memory_abc123",
      "relevance_score": 0.92,
      "content": {
        "type": "episodic",
        "summary": "Previous decision to prioritize performance over features",
        "details": "Performance issues were affecting user retention in mobile app",
        "outcome": "Successful performance optimization led to 15% improvement in user retention"
      }
    }
  ],
  "retrieval_metadata": {
    "total_matches": 5,
    "search_time": "0.045s",
    "memory_layers_searched": ["episodic", "semantic", "procedural"]
  }
}

Decision Support

Generate Decision

Generate a decision recommendation with cultural context.

POST /decisions/generate

Request Body:

{
  "decision_context": {
    "type": "resource_allocation",
    "description": "Allocate development resources between bug fixes and new features",
    "stakeholders": [
      {
        "user_id": "user_123",
        "subculture": "engineering",
        "influence": 0.7
      },
      {
        "user_id": "user_456",
        "subculture": "product",
        "influence": 0.8
      }
    ]
  },
  "constraints": {
    "timeline": "2_weeks",
    "budget": 50000,
    "team_size": 5
  },
  "options": [
    {
      "id": "option_1",
      "description": "Focus 80% on bug fixes, 20% on new features",
      "engineering_impact": "high",
      "product_impact": "medium"
    },
    {
      "id": "option_2",
      "description": "Focus 50% on bug fixes, 50% on new features",
      "engineering_impact": "medium",
      "product_impact": "high"
    }
  ]
}

Response:

{
  "recommendation": {
    "option_id": "option_1",
    "confidence": 0.82,
    "reasoning": "Bug fixes are critical for user retention and system stability",
    "cultural_considerations": {
      "engineering_perspective": "Technical debt reduction is essential for long-term success",
      "product_perspective": "User experience improvements will drive engagement"
    }
  },
  "alternatives": [
    {
      "option_id": "option_2",
      "confidence": 0.68,
      "reasoning": "Balanced approach but may not address critical issues"
    }
  ],
  "decision_metadata": {
    "generation_time": "2024-01-15T10:33:00Z",
    "cultural_analysis": true,
    "trust_integration": true
  }
}

Webhooks

Event Types

The MSM System can send webhooks for various events:

cultural_analysis.completed
translation.completed
trust_score.updated
decision.generated
memory.stored

Webhook Payload

{
  "event_type": "cultural_analysis.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "user_id": "user_123",
    "subculture": "engineering",
    "confidence": 0.87
  }
}

Webhook Configuration

POST /webhooks/configure

Request Body:

{
  "url": "https://your-app.com/webhooks/msm",
  "events": ["cultural_analysis.completed", "translation.completed"],
  "secret": "your_webhook_secret"
}

SDKs and Libraries

Python SDK

from metacogna import MSMClient

client = MSMClient(api_key="your_api_key")

# Detect subculture
subculture = client.cultural_analysis.detect(
    user_id="user_123",
    communication_data=communication_data
)

# Translate message
translation = client.translation.translate(
    message="Technical message",
    source_subculture="engineering",
    target_subculture="product"
)

JavaScript SDK

import { MSMClient } from '@metacogna/msm-sdk';

const client = new MSMClient('your_api_key');

// Detect subculture
const subculture = await client.culturalAnalysis.detect({
  userId: 'user_123',
  communicationData: communicationData
});

// Translate message
const translation = await client.translation.translate({
  message: 'Technical message',
  sourceSubculture: 'engineering',
  targetSubculture: 'product'
});

Testing

Sandbox Environment

Use the sandbox environment for testing:

https://sandbox-api.metacogna.com/v1

API Reference

Base URL

Authentication

API Key Authentication

OAuth 2.0 Authentication

Rate Limiting

Error Handling

Common Error Codes

Core Endpoints

Cultural Analysis

Detect Subculture

Analyze Cultural Dynamics

Cultural Translation

Translate Message

Batch Translation

Trust Management

Calculate Trust Score

Update Trust Metrics

Memory Management

Store Interaction

Retrieve Context

Decision Support

Generate Decision

Webhooks

Event Types

Webhook Payload

Webhook Configuration

SDKs and Libraries

Python SDK

JavaScript SDK

Testing

Sandbox Environment

Test Data

Rate Limits

Support

Documentation

Contact

Base URL​

Authentication​

API Key Authentication​

OAuth 2.0 Authentication​

Rate Limiting​

Error Handling​

Common Error Codes​

Core Endpoints​

Cultural Analysis​

Detect Subculture​

Analyze Cultural Dynamics​

Cultural Translation​

Translate Message​

Batch Translation​

Trust Management​

Calculate Trust Score​

Update Trust Metrics​

Memory Management​

Store Interaction​

Retrieve Context​

Decision Support​

Generate Decision​

Webhooks​

Event Types​

Webhook Payload​

Webhook Configuration​

SDKs and Libraries​

Python SDK​

JavaScript SDK​

Testing​

Sandbox Environment​

Test Data​

Rate Limits​

Support​

Documentation​

Contact​

Base URL

Authentication

API Key Authentication

OAuth 2.0 Authentication

Rate Limiting

Error Handling

Common Error Codes

Core Endpoints

Cultural Analysis

Detect Subculture

Analyze Cultural Dynamics

Cultural Translation

Translate Message

Batch Translation

Trust Management

Calculate Trust Score

Update Trust Metrics

Memory Management

Store Interaction

Retrieve Context

Decision Support

Generate Decision

Webhooks

Event Types

Webhook Payload

Webhook Configuration

SDKs and Libraries

Python SDK

JavaScript SDK

Testing

Sandbox Environment

Test Data

Rate Limits

Support

Documentation

Contact