Documentation
POST

Evaluation API

/railscore/v1/eval

Score content across 8 RAIL dimensions with basic or deep analysis modes.

Score frameworkFairnessSafetyReliabilityTransparencyPrivacyAccountabilityInclusivityUser Impact

Authentication: Required — Authorization: Bearer YOUR_RAIL_API_KEY

Caching: Basic mode cached 5 min, deep mode cached 3 min. Identical requests within the window return from_cache: true.

Rate limits: Plan-dependent. See Authentication for per-plan limits.

Evaluation Pipeline

Content + Parameters

Scoring Layer

ML Classifier

8 dimensions

Safety Check

toxicity signals

Privacy NLP

PII detection

Deep mode only
LLM Judge

explanations + issues

Overall Score

weighted avg

8 Dim Scores

0–10 each

Confidence

0–1 per dim

Explanations

deep only

When to Use

Use basic mode for quick, cost-effective scoring across all 8 dimensions. Use deep mode when you need per-dimension explanations, issue detection, and improvement suggestions. See the Credits & Pricing page for cost details per mode.

Parameters

ParameterTypeRequiredDescription
contentstringYesText to evaluate (10 – 10,000 characters)
modestringYesOne of: "basic" or "deep". Deep mode includes per-dimension explanations and issue detection.
dimensionsstring[]NoSubset of dimensions to evaluate. Omit for all 8. Valid values: fairness, safety, reliability, transparency, privacy, accountability, inclusivity, user_impact.
weightsobjectNoCustom weights (must sum to 100.0). Keys are dimension names.
contextstringNoAdditional context for evaluation (max 1,000 chars)
include_explanationsbooleanNoInclude per-dimension explanations. Default: true for deep, false for basic.
include_issuesbooleanNoInclude per-dimension issue tags. Default: true for deep, false for basic.
include_suggestionsbooleanNoInclude improvement suggestions. Default: false.
domainstringNoContent domain. One of: general, healthcare, finance, legal, education, technology
usecasestringNoUse case category. One of: chatbot, content_generation, summarization, translation, code_generation

Request Examples

Basic scoring (all dimensions)

Request
curl -X POST https://api.responsibleailabs.ai/railscore/v1/eval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RAIL_API_KEY" \
  -d '{
    "content": "There are several natural approaches that may help with insomnia. Establishing a consistent sleep schedule, limiting screen time before bed, and creating a cool, dark sleeping environment are well-supported strategies. Some people find herbal teas like chamomile or valerian root helpful, though scientific evidence is mixed. If sleep problems persist for more than a few weeks, consulting a healthcare provider is recommended to rule out underlying conditions.",
    "mode": "basic"
  }'

Deep mode with explanations

Request
curl -X POST https://api.responsibleailabs.ai/railscore/v1/eval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RAIL_API_KEY" \
  -d '{
    "content": "When reviewing resumes, prioritize candidates from top-tier universities like Stanford and MIT. Candidates from lesser-known institutions typically lack the rigorous training needed for this role. Additionally, candidates who took career breaks are likely less committed to professional growth.",
    "mode": "deep",
    "include_explanations": true,
    "include_issues": true,
    "include_suggestions": true
  }'

Single dimension evaluation

Request
curl -X POST https://api.responsibleailabs.ai/railscore/v1/eval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RAIL_API_KEY" \
  -d '{
    "content": "To reset your password, click the link sent to john.doe@company.com. For verification, your employee ID is EMP-29481 and your account was registered from 192.168.1.42 on March 3rd.",
    "mode": "basic",
    "dimensions": ["privacy"]
  }'

Custom weights for healthcare

Request
curl -X POST https://api.responsibleailabs.ai/railscore/v1/eval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RAIL_API_KEY" \
  -d '{
    "content": "Based on your described symptoms of chest tightness and shortness of breath, you should take 325mg aspirin immediately and lie down. This is likely a mild cardiac event that will resolve on its own without medical intervention.",
    "mode": "deep",
    "domain": "healthcare",
    "weights": {
      "safety": 25, "privacy": 20, "reliability": 20,
      "accountability": 15, "transparency": 10,
      "fairness": 5, "inclusivity": 3, "user_impact": 2
    }
  }'

Response Format

Success Response200 OK

Response
{
  "result": {
    "rail_score": {
      "score": 5.9,
      "confidence": 0.7,
      "summary": "RAIL Score: 5.9/10 — Needs improvement"
    },
    "dimension_scores": {
      "fairness":       { "score": 2.0, "confidence": 0.9 },
      "safety":         { "score": 3.0, "confidence": 0.8 },
      "reliability":    { "score": 9.0, "confidence": 0.95 },
      "transparency":   { "score": 9.0, "confidence": 0.9 },
      "privacy":        { "score": 10.0, "confidence": 1.0 },
      "accountability": { "score": 8.0, "confidence": 0.8 },
      "inclusivity":    { "score": 2.0, "confidence": 0.85 },
      "user_impact":    { "score": 4.0, "confidence": 0.75 }
    },
    "explanation": "Overall holistic summary across dimensions...",
    "issues": [
      { "dimension": "fairness", "description": "Gender-based generalization" }
    ],
    "improvement_suggestions": ["Consider rephrasing..."],
    "from_cache": false
  },
  "metadata": {
    "req_id": "b00379a5-d6a7-45d6-905c-82925666a616",
    "mode": "basic",
    "timestamp": "2026-02-26T10:30:00.000000Z"
  },
  "credits_consumed": 1.0
}

Response Fields

result.rail_score.scoreOverall RAIL score (0.0 – 10.0)
result.rail_score.confidenceConfidence in the overall score (0.0 – 1.0)
result.dimension_scores.*Per-dimension score, confidence, and optionally explanation + issues
result.from_cacheWhether this result was served from cache (0 credits if true)
metadata.req_idUnique request ID for debugging
metadata.modeEvaluation mode used: basic or deep
credits_consumedCredits charged for this request

Error Codes

400Invalid content length, invalid mode, invalid weights or dimensions
401Missing or invalid API key
402Insufficient credits
429Rate limit exceeded
500Evaluation failed

Error Response Examples

400 — Validation Error
{
  "error": "Content must be between 10 and 10000 characters",
  "code": "VALIDATION_ERROR"
}
401 — Authentication Error
{
  "error": "Invalid or missing API key",
  "code": "AUTHENTICATION_ERROR"
}
402 — Insufficient Credits
{
  "error": "Insufficient credits: 0.5 available, 3.0 required",
  "code": "INSUFFICIENT_CREDITS",
  "balance": 0.5,
  "required": 3.0
}
429 — Rate Limit Exceeded
{
  "error": "Rate limit exceeded. Try again in 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}