API Reference

The IntentEmoji API provides four endpoints for emoji placement, analysis, repositioning, and suggestion. All endpoints accept JSON and return JSON. Base URL: https://api.intentemoji.com

Authentication

All API requests require an API key passed in the Authorization header.

Authorization: Bearer ie_live_abc123def456

API keys are available in your dashboard. Keys are prefixed with ie_live_ for production and ie_test_ for development.

Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1711929600

POST /v1/enhance

curl -X POST https://api.intentemoji.com/v1/enhance \
  -H "Authorization: Bearer ie_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "We shipped the new billing system today. Invoices now generate in under 2 seconds. The old system took 15 seconds on average.",
    "profile": "professional",
    "density": "moderate"
  }'

{
  "text": "🚀 We shipped the new billing system today.\n\n⚡ Invoices now generate in under 2 seconds. The old system took 15 seconds on average.",
  "emoji_count": 2,
  "positions": [
    {
      "emoji": "🚀",
      "position": "preload",
      "index": 0,
      "context": "We shipped the new billing system today."
    },
    {
      "emoji": "⚡",
      "position": "preload",
      "index": 44,
      "context": "Invoices now generate in under 2 seconds."
    }
  ],
  "profile": "professional",
  "density": "moderate",
  "preload_ratio": 1.0,
  "usage": {
    "characters_in": 124,
    "characters_out": 132
  }
}

POST /v1/analyze

curl -X POST https://api.intentemoji.com/v1/analyze \
  -H "Authorization: Bearer ie_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Just deployed the update 🚀 Everything looks good so far 👍 Will monitor overnight 🔍",
    "target_profile": "professional"
  }'

{
  "emoji_count": 3,
  "sentence_count": 3,
  "density": "high",
  "density_ratio": 1.0,
  "positions": [
    { "emoji": "🚀", "position": "postload", "index": 28 },
    { "emoji": "👍", "position": "postload", "index": 57 },
    { "emoji": "🔍", "position": "postload", "index": 82 }
  ],
  "preload_count": 0,
  "postload_count": 3,
  "inline_count": 0,
  "preload_ratio": 0.0,
  "target_profile": "professional",
  "score": 32,
  "suggestions": [
    "All emoji is postloaded. Consider repositioning to preload for cognitive priming.",
    "Density is higher than the professional profile target. Consider reducing to 1 emoji per 2-4 sentences.",
    "👍 is informal for professional context. Consider ✅ or removing."
  ]
}

POST /v1/reposition

curl -X POST https://api.intentemoji.com/v1/reposition \
  -H "Authorization: Bearer ie_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The server crashed at 3am 💥 We lost 2 hours of data 😬 Root cause was a memory leak 🐛",
    "profile": "professional"
  }'

{
  "text": "💥 The server crashed at 3am. We lost 2 hours of data. 🐛 Root cause was a memory leak.",
  "repositioned": [
    {
      "emoji": "💥",
      "from": "postload",
      "to": "preload",
      "reason": "Moved to preload position to prime reader for severity of the incident."
    },
    {
      "emoji": "😬",
      "action": "removed",
      "reason": "Informal for professional profile. Not repositioned."
    },
    {
      "emoji": "🐛",
      "from": "postload",
      "to": "preload",
      "reason": "Moved to preload position to signal technical root cause."
    }
  ],
  "preload_ratio": 1.0,
  "emoji_removed": 1,
  "emoji_moved": 2
}

GET /v1/suggest

curl "https://api.intentemoji.com/v1/suggest?text=Deployment%20complete.%20All%20tests%20passing.&profile=technical&limit=3" \
  -H "Authorization: Bearer ie_live_abc123def456"

{
  "suggestions": [
    {
      "emoji": "✅",
      "position": "preload",
      "confidence": 0.94,
      "reason": "Strong semantic match for completion and success. High congruence with 'complete' and 'passing'."
    },
    {
      "emoji": "🚀",
      "position": "preload",
      "confidence": 0.87,
      "reason": "Common deployment indicator. Slightly less precise than ✅ but widely recognized in technical contexts."
    },
    {
      "emoji": "🟢",
      "position": "preload",
      "confidence": 0.82,
      "reason": "Status indicator. Maps well to 'all tests passing' as a green/success signal."
    }
  ],
  "profile": "technical",
  "text": "Deployment complete. All tests passing."
}

Error Codes

The API returns standard HTTP status codes with a JSON error body.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your rate limit of 10 requests per minute.",
    "status": 429
  }
}

Versioning

The API is versioned in the URL path (/v1/). Breaking changes will be introduced in new versions. Non-breaking additions (new fields in responses, new optional parameters) may be added to existing versions without notice.