Score Content

Score your content titles and descriptions against platform best practices using deterministic analysis.

POST /api/v1/content/score

Score content (titles or descriptions) against platform-specific best practices. Uses deterministic analysis to evaluate keyword placement, length optimization, emotional pull, curiosity gap, readability, and more.

Credits: 2 per request

Authentication

X-Soke-Key: sk_live_your_api_key

Authorization: Bearer your_jwt_token

Request Body

Field	Type	Required	Default	Description
`content`	string	Yes	—	The title or description to score
`platform`	string	No	`"youtube"`	Target platform
`targetKeywords`	string[]	No	—	Keywords to evaluate placement for

Example Request

curl -X POST https://api.usesoke.ai/api/v1/content/score \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{
    "content": "10 Developer Productivity Hacks That Actually Work",
    "platform": "youtube",
    "targetKeywords": ["developer productivity"]
  }'

Response

200 OK

{
  "success": true,
  "data": {
    "content": "10 Developer Productivity Hacks That Actually Work",
    "overallScore": 85.3,
    "breakdown": {
      "keywordPlacement": {
        "value": 90.0,
        "dimension": "Keyword Placement",
        "suggestion": null
      },
      "lengthOptimization": {
        "value": 88.0,
        "dimension": "Length Optimization",
        "suggestion": null
      },
      "emotionalPull": {
        "value": 75.0,
        "dimension": "Emotional Pull",
        "suggestion": "Consider adding a stronger emotional trigger word"
      },
      "curiosityGap": {
        "value": 82.0,
        "dimension": "Curiosity Gap",
        "suggestion": null
      },
      "readability": {
        "value": 92.0,
        "dimension": "Readability",
        "suggestion": null
      },
      "personalTone": {
        "value": 78.0,
        "dimension": "Personal Tone",
        "suggestion": "Consider using 'I' or 'You' for a more personal feel"
      },
      "hookStrength": {
        "value": 88.0,
        "dimension": "Hook Strength",
        "suggestion": null
      },
      "authenticity": {
        "value": 90.0,
        "dimension": "Authenticity",
        "suggestion": null
      }
    },
    "suggestions": [
      "Consider adding a stronger emotional trigger word",
      "Consider using 'I' or 'You' for a more personal feel"
    ]
  },
  "meta": {
    "platform": "youtube",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_time_ms": 95
  }
}

Score Dimensions

Dimension	Description
`keywordPlacement`	How well target keywords are positioned
`lengthOptimization`	Whether the length is optimal for the platform
`emotionalPull`	Emotional appeal and trigger words
`curiosityGap`	Whether it creates curiosity to click
`readability`	How easy it is to read and understand
`personalTone`	Use of personal language (I, You)
`hookStrength`	Strength of the opening hook (numbers, questions, etc.)
`authenticity`	How authentic and non-clickbaity it feels

Each dimension returns a value (0-100) and an optional suggestion for improvement.

Error Codes

Code	Status	Description
`BAD_REQUEST`	400	Missing or invalid `content`
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`INSUFFICIENT_CREDITS`	402	Not enough credits
`PLATFORM_NOT_IMPLEMENTED`	501	Platform not yet supported