API Reference

Complete REST API documentation for Classy Comments

Authentication

All API requests require an API key passed in the X-API-Key header.

curl https://api.classycomments.com/api/refine \
  -H "X-API-Key: cc_live_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "THIS IS GREAT!!!"}'

API Key Format

  • cc_live_sk_* - Production API keys
  • cc_demo_sk_* - Demo API keys (limited features)

Base URL

https://api.classycomments.com

Rate Limits

EndpointLimit
General endpoints100 requests per 15 minutes
Classification endpoint20 requests per minute
Authentication endpoints5 requests per 15 minutes

Refine Comment

POST /api/refine

Refine a comment using AI or demo mode.

Config comes from your dashboard

The config parameter is optional. If omitted, the API uses the settings you configured in your dashboard. This is the recommended approach—configure once, use everywhere!

Request Body

{
  "text": "THIS IS AWESOME!!! ur plugin is the best",
  // Optional: Override dashboard settings
  "config": {
    "formalityLevel": 3,
    "tone": "friendly",
    "profanityHandling": "soften",
    "emojiHandling": "remove",
    "capsCorrection": true,
    "punctuationCleanup": true,
    "grammarStrictness": 3,
    "lengthPreference": "keep"
  },
  "mode": "ai",  // or "demo"
  "domain": "example.com"
}

Response

{
  "success": true,
  "data": {
    "id": 123,
    "originalText": "THIS IS AWESOME!!! ur plugin is the best",
    "refinedText": "This is awesome! Your plugin is the best.",
    "status": "completed",
    "processingTimeMs": 1234,
    "provider": "openai",
    "model": "gpt-4",
    "changeScore": 0.42
  }
}

Parameters

FieldTypeRequiredDescription
textstringYesComment text to refine
configobjectNoRefinement configuration (uses defaults if omitted)
modestringNo"ai" or "demo" (default: uses client config)
domainstringNoOrigin domain for analytics

Classify Comment

POST /api/classify

Classify a comment's toxicity, sentiment, and language.

Request Body

{
  "text": "Great article! Thanks for sharing."
}

Response

{
  "toxicity": 0.02,
  "sentiment": "positive",
  "language": "en",
  "needsRefinement": false
}

Get Statistics

GET /api/users/me/clients/:clientId/stats

Retrieve usage statistics for your client account.

Response

{
  "totalComments": 1234,
  "monthlyUsage": 456,
  "quota": 1000,
  "quotaRemaining": 544,
  "domains": 3,
  "apiKeys": 2
}

Error Codes

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Quota exceeded or domain not allowed
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

JavaScript Client

For client-side integration, use the @classy-comments/core package:

npm install @classy-comments/core

import { ClassyComments } from '@classy-comments/core'
import '@classy-comments/core/styles.css'

const classy = new ClassyComments({
  apiBaseUrl: 'https://api.classycomments.com',
  apiKey: 'cc_live_sk_your_api_key',
  formalityLevel: 3,
  tone: 'friendly',
  profanityHandling: 'soften',
  emojiHandling: 'remove',
  capsCorrection: true,
  punctuationCleanup: true
})

await classy.init()

// Process a comment
const result = await classy.processCommentManual('THIS IS GREAT!!!', {
  onApprove: (refined) => console.log('Approved:', refined),
  onCancel: () => console.log('Cancelled')
})

Need Help?

For API support and questions:

Check FAQGitHubEmail API Support