COS Content Analysis API: 7-Framework Communication Intelligence

Authentication

The COS API supports three authentication methods. Anonymous access works for testing and low-volume use. API keys are available for production integrations.

Method	Header	Rate Limit
Anonymous	X-Session-ID: your-session-id	30 requests / hour
User JWT	Authorization: Bearer <token>	Plan-based
API Key	Authorization: Bearer cos_api_...	Credit-based

For anonymous access, pass any unique string as the X-Session-ID header. This identifies your session for rate limiting. No signup required.

Quick Start Example

Send your content to any endpoint with a JSON body. Here is a minimal example using the quality analysis endpoint:

POST https://semalytics.com/api/analyze/quality
Content-Type: application/json
X-Session-ID: my-test-session

{
  "content": "Your marketing copy goes here. The COS API needs at
    least 50 characters to analyze, so include a real paragraph
    of the content you want scored.",
  "platform": "linkedin",
  "target_audience": "B2B marketing directors",
  "target_keywords": ["marketing copy analysis", "B2B content optimization"]
}

cURL example:

curl -X POST https://semalytics.com/api/analyze/quality \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: my-test-session" \
  -d '{
    "content": "Your marketing copy goes here...",
    "platform": "linkedin",
    "target_audience": "B2B marketing directors",
    "target_keywords": ["marketing copy analysis", "B2B content"]
  }'

Request Body

Every analysis endpoint accepts the same request body:

Field	Type	Required	Description
content	string	required	The text to analyze. Minimum 50 characters.
platform	string	optional	Target platform. Defaults to "general". Affects scoring context.
target_audience	string	optional	Description of your intended audience. Improves recommendation relevance.
target_keywords	array	optional	SEO keywords to protect during optimization. Max 5. Accepts strings (first = primary, rest = secondary) or objects: {"keyword": "...", "priority": "primary|secondary"}. When provided, the Quality framework adds a 6th dimension: Keyword Coherence.

Core Framework Endpoints

Four core frameworks form the foundation of COS analysis. Each runs independently and returns a score, dimensional breakdown, analysis narrative, and actionable recommendations.

Response Format

All four core endpoints return the same response structure:

{
  "framework": "hape",
  "overall_score": 7.5,
  "dimensions": [
    {
      "name": "Identity Recognition",
      "score": 8.2,
      "weight": 0.125,
      "details": "Content names specific buyer role..."
    }
    // ... additional dimensions
  ],
  "analysis": "Detailed narrative analysis...",
  "recommendations": [
    "Strengthen the Efficacy dimension...",
    "Add specific evidence for the claim..."
  ]
}

Field	Type	Description
framework	string	Framework identifier (hape, big_five, strategic_clarity, framing_strategy)
overall_score	float	Weighted score from 0.0 to 10.0
dimensions	array	Individual dimension scores with names, weights, and explanations
analysis	string	Written analysis explaining the score and key observations
recommendations	array	Specific, actionable suggestions for improving the content

Full Multi-Framework Analysis

POST https://semalytics.com/api/analyze/full

{
  "content": "Your B2B content here...",
  "platform": "email",
  "target_audience": "SaaS founders, Series A-B"
}

Response

{
  "hape": { /* engagement analysis */ },
  "big_five": { /* personality analysis */ },
  "strategic_clarity": { /* clarity analysis */ },
  "framing_strategy": { /* framing analysis */ },
  "combined_score": 7.2,
  "summary": "Multi-framework analysis complete..."
}

Each framework field contains the full response structure described above. If a framework encounters an error, its field will be null and the combined score will be calculated from the remaining frameworks.

Domain-Specific Persuasion

Available Domains

Domain	Focus
business	B2B/B2C persuasion, ROI framing, stakeholder alignment
politics	Political messaging, moral foundations, polarization management
health	Medical communication, safety protocols, evidence standards
masculinity	Identity-affirming content, status preservation, reframing
comedy	Humor mechanics, timing, information gap theory

POST https://semalytics.com/api/analyze/persuasion/business

{
  "content": "Your sales email copy...",
  "target_audience": "VP Sales at mid-market SaaS"
}

Response

{
  "framework": "persuasion",
  "domain": "business",
  "overall_score": 6.8,
  "dimensions": [ /* domain-specific dimensions */ ],
  "analysis": "...",
  "recommendations": ["..."],
  "strengths": ["Strong ROI framing..."],
  "warnings": ["Urgency tactic may backfire..."]
}

Platform-Specific Analysis

Supported Platforms

Platform	Focus
twitter	Short-form, real-time, character limits, thread structure
linkedin	Professional tone, B2B context, algorithm hooks
email	Subject line, personalization, deliverability signals
youtube	Title/description SEO, thumbnail strategy, retention
tiktok	Hook timing, trend alignment, short-form pacing
instagram	Visual-first, caption length, hashtag strategy
facebook	Community tone, group dynamics, share triggers
medium	Long-form structure, curation signals, reading time
substack	Newsletter structure, subscriber retention, voice consistency
podcast	Show notes, discoverability, episode structure
newsletter	Email marketing, open/click patterns, list hygiene
slack	Internal comms, channel norms, message density
discord	Community chat, real-time interaction, moderation tone

Response

{
  "framework": "platform",
  "platform": "linkedin",
  "overall_score": 7.1,
  "dimensions": [ /* platform-specific dimensions */ ],
  "constraint_check": {
    "passed": true,
    "violations": [],
    "warnings": ["Post exceeds 1300 chars, may be truncated"]
  },
  "analysis": "...",
  "recommendations": ["..."],
  "algorithm_tips": ["Open with a hook question for higher dwell time"]
}

Quality Assessment

Quality Levels

Score Range	Level
8.0 - 10.0	Excellent
6.0 - 7.9	Good
4.0 - 5.9	Needs Work
0.0 - 3.9	Significant Issues

Response

{
  "framework": "quality",
  "overall_score": 7.8,
  "quality_level": "Good",
  "dimensions": [
    { "name": "Scientific Rigor", "score": 8.0, "weight": 0.2 },
    { "name": "Practical Utility", "score": 7.5, "weight": 0.2 },
    { "name": "Ethical Compliance", "score": 9.0, "weight": 0.2 },
    { "name": "Integration Coherence", "score": 7.2, "weight": 0.2 },
    { "name": "Performance Effectiveness", "score": 7.3, "weight": 0.2 }
  ],
  "critical_issues": [],
  "analysis": "...",
  "recommendations": ["..."]
}

Full 7-Framework Communications Analysis

Query Parameters

Parameter	Default	Description
domain	business	Persuasion domain (business, politics, health, masculinity, comedy)
platform	linkedin	Target platform for platform-specific analysis

POST https://semalytics.com/api/analyze/full-comms?domain=business&platform=linkedin

{
  "content": "Your content to analyze...",
  "target_audience": "Marketing directors at B2B SaaS"
}

Response

{
  "hape": { /* engagement scores + analysis */ },
  "big_five": { /* personality scores + analysis */ },
  "strategic_clarity": { /* clarity scores + analysis */ },
  "framing_strategy": { /* framing scores + analysis */ },
  "persuasion": { /* domain-specific + strengths/warnings */ },
  "platform": { /* platform-specific + constraint_check */ },
  "quality": { /* quality level + critical issues */ },
  "combined_score": 7.4,
  "framework_count": 7,
  "summary": "Full communications analysis complete..."
}

Rate Limits & Errors

Rate Limits

Auth Method	Limit	Window
Anonymous (X-Session-ID)	30 requests	1 hour
User JWT	Plan-based	Varies
Developer API Key	Credit-based	Per-request billing

Error Responses

Status	Meaning	Common Cause
400	Bad Request	Content under 50 characters, invalid domain/platform parameter
401	Unauthorized	Missing or invalid authentication token
402	Payment Required	Insufficient API credits (developer key only)
429	Too Many Requests	Rate limit exceeded. Response includes reset_at timestamp.
500	Server Error	Analysis framework encountered an internal error

Error Response Format

{
  "detail": "Content must be at least 50 characters"
}

// Rate limit exceeded:
{
  "detail": {
    "reset_at": "2026-03-26T15:30:00"
  }
}

Python Example

# pip install requests
import requests

response = requests.post(
    "https://semalytics.com/api/analyze/full",
    headers={
        "Content-Type": "application/json",
        "X-Session-ID": "my-integration-001"
    },
    json={
        "content": """We built COS because we noticed something
        every B2B team experiences but few measure: the same
        email lands differently with different buyers. Not because
        of the product. Because of the personality reading it.""",
        "platform": "email",
        "target_audience": "B2B revenue leaders"
    }
)

result = response.json()
print(f"Combined Score: {result['combined_score']}/10")

for fw in ["hape", "big_five", "strategic_clarity", "framing_strategy"]:
    if result.get(fw):
        print(f"  {fw}: {result[fw]['overall_score']}/10")

JavaScript Example

const response = await fetch(
  "https://semalytics.com/api/analyze/full-comms?domain=business&platform=linkedin",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Session-ID": "my-app-session"
    },
    body: JSON.stringify({
      content: "Your LinkedIn post copy here...",
      platform: "linkedin",
      target_audience: "Marketing directors at B2B SaaS"
    })
  }
);

const data = await response.json();
console.log(`Score: ${data.combined_score}/10`);
console.log(`Frameworks analyzed: ${data.framework_count}`);

For questions about API access, integration support, or higher rate limits, reach out at api@semalytics.com.