Documentation
POST

Safe-Regenerate API

/railscore/v1/safe-regenerate

Evaluate content against quality thresholds and iteratively regenerate improved versions until targets are met.

Authentication: Required — Authorization: Bearer YOUR_RAIL_API_KEY

Content limit: 10 – 10,000 characters

Caching: Not cached — each request performs a fresh evaluation and regeneration cycle.

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

When to Use

Use this endpoint when you need content that meets specific quality thresholds — the API handles the evaluate, improve, and re-evaluate loop automatically. If you only need scoring without regeneration, use the Evaluation API instead.

How It Works

Safe-Regenerate: Evaluation Loop

Input Content
Evaluate (RAIL API)
Score ≥ Threshold?

✓ Yes

Return Best Content

✗ No

Regenerate Improved Version
re-evaluates

Repeats up to max_regenerations (1–5) times

  1. 1.Your content is evaluated across RAIL dimensions using the specified mode (basic or deep).
  2. 2.If any dimension scores fall below thresholds, the server generates an improvement prompt and regenerates the content.
  3. 3.The regenerated content is re-evaluated. This loop continues until thresholds pass or max iterations are reached.

Parameters

ParameterTypeRequiredDescription
contentstringYesText to evaluate and regenerate (10 – 10,000 characters)
modestringNoOne of: "basic" or "deep". Default: "basic"
max_regenerationsintegerNoMaximum regeneration iterations (1–5). Default: 3
thresholdsobjectNoThreshold configuration (see below)
contextstringNoAdditional context for evaluation (max 1,000 chars)
domainstringNoContent domain. One of: general, healthcare, finance, legal
weightsobjectNoCustom dimension weights (must sum to 100.0)
policy_hintstringNoAdditional policy guidance for regeneration

Thresholds Object

FieldTypeDefaultDescription
overall.scorefloat7.0Minimum overall RAIL score to pass
overall.confidencefloat0.5Minimum confidence to accept score
tradeoff_modestringpriorityOne of: priority, strict, weighted
max_dimension_failuresinteger2Max dimensions allowed to fail before regeneration
dimensionsobjectPer-dimension threshold overrides (e.g., {"safety": 8.0})

Tradeoff Modes

ModeBehavior
priorityDimensions with custom thresholds must pass individually. Other dimensions only need to meet the overall threshold. Best for focusing on specific dimensions.
strictALL dimensions must pass their threshold individually. Most rigorous — use for high-stakes content.
weightedThe weighted average across dimensions must pass. Individual dimensions can be below threshold as long as the overall score is sufficient.

Request Example

Request
curl -X POST https://api.responsibleailabs.ai/railscore/v1/safe-regenerate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RAIL_API_KEY" \
  -d '{
    "content": "Based on your symptoms, you likely have condition X. Take 500mg of medication Y twice daily. No need to see a doctor for this.",
    "mode": "basic",
    "max_regenerations": 3,
    "thresholds": {
      "overall": { "score": 7.0, "confidence": 0.5 },
      "tradeoff_mode": "priority",
      "max_dimension_failures": 2,
      "dimensions": {
        "safety": 8.0,
        "reliability": 8.0
      }
    },
    "domain": "healthcare"
  }'

Response Example

200 OK — Passed
{
  "result": {
    "status": "passed",
    "best_content": "Based on these symptoms, it would be important to consult a healthcare professional for proper diagnosis. Some possibilities include condition X, but only a qualified doctor can make an accurate assessment after examination. Please do not self-medicate without professional guidance.",
    "best_iteration": 2,
    "original_content": "Based on your symptoms, you likely have condition X. Take 500mg of medication Y twice daily. No need to see a doctor for this.",
    "best_scores": {
      "rail_score": {
        "score": 8.1,
        "confidence": 0.82,
        "summary": "RAIL Score: 8.1/10 — Good"
      },
      "dimension_scores": {
        "fairness":       { "score": 8.0, "confidence": 0.85 },
        "safety":         { "score": 9.0, "confidence": 0.90 },
        "reliability":    { "score": 8.5, "confidence": 0.84 },
        "transparency":   { "score": 7.0, "confidence": 0.78 },
        "privacy":        { "score": 5.0, "confidence": 1.0 },
        "accountability": { "score": 8.0, "confidence": 0.80 },
        "inclusivity":    { "score": 8.0, "confidence": 0.82 },
        "user_impact":    { "score": 8.5, "confidence": 0.86 }
      },
      "thresholds_met": {
        "overall_passed": true,
        "all_passed": true,
        "dimension_results": {
          "safety":      { "score": 9.0, "threshold": 8.0, "passed": true },
          "reliability": { "score": 8.5, "threshold": 8.0, "passed": true }
        }
      }
    },
    "iteration_history": [
      {
        "iteration": 0,
        "thresholds_met": false,
        "failing_dimensions": ["safety", "reliability", "accountability"],
        "improvement_from_previous": 0.0
      },
      {
        "iteration": 1,
        "thresholds_met": false,
        "failing_dimensions": ["reliability"],
        "improvement_from_previous": 2.8
      },
      {
        "iteration": 2,
        "thresholds_met": true,
        "failing_dimensions": [],
        "improvement_from_previous": 0.9
      }
    ]
  },
  "metadata": {
    "req_id": "38b85d5d-de9f-4af8-a0d3-886bfe68c06f",
    "mode": "basic",
    "total_iterations": 3
  },
  "credits_consumed": 7.0,
  "credits_breakdown": {
    "evaluations": 3.0,
    "regenerations": 4.0,
    "total": 7.0
  }
}
200 OK — Max Iterations Reached
{
  "result": {
    "status": "max_iterations_reached",
    "best_content": "Based on these symptoms, consulting a healthcare professional is strongly recommended for proper diagnosis. Possible conditions include X, but self-diagnosis is unreliable. Please seek medical advice before taking any medication.",
    "best_iteration": 2,
    "original_content": "Based on your symptoms, you likely have condition X. Take 500mg of medication Y twice daily. No need to see a doctor for this.",
    "best_scores": {
      "rail_score": {
        "score": 6.8,
        "confidence": 0.74,
        "summary": "RAIL Score: 6.8/10 — Needs Improvement"
      },
      "dimension_scores": {
        "safety":      { "score": 7.5, "confidence": 0.82 },
        "reliability": { "score": 6.0, "confidence": 0.70 }
      },
      "thresholds_met": {
        "overall_passed": false,
        "all_passed": false,
        "dimension_results": {
          "safety":      { "score": 7.5, "threshold": 8.0, "passed": false },
          "reliability": { "score": 6.0, "threshold": 8.0, "passed": false }
        }
      }
    },
    "iteration_history": [
      { "iteration": 0, "thresholds_met": false, "failing_dimensions": ["safety", "reliability"], "improvement_from_previous": 0.0 },
      { "iteration": 1, "thresholds_met": false, "failing_dimensions": ["safety", "reliability"], "improvement_from_previous": 2.1 },
      { "iteration": 2, "thresholds_met": false, "failing_dimensions": ["safety", "reliability"], "improvement_from_previous": 0.4 }
    ]
  },
  "metadata": { "req_id": "...", "mode": "basic", "total_iterations": 3 },
  "credits_consumed": 7.0,
  "credits_breakdown": { "evaluations": 3.0, "regenerations": 4.0, "total": 7.0 }
}

When status is max_iterations_reached, the best_content field still contains the highest-scoring version produced during the loop — even though it did not meet all thresholds.

Response Fields

result.statuspassed or max_iterations_reached
result.best_contentThe highest-scoring version of the content
result.best_iterationWhich iteration produced the best content (0 = original)
result.original_contentThe original input content
result.best_scoresRAIL scores for the best iteration: rail_score, dimension_scores, thresholds_met
result.iteration_historyArray of per-iteration results with failing dimensions and score improvement
credits_breakdownBreakdown of credits for evaluations vs. regenerations

Critical Content (422)

If the content contains critical ethical violations that cannot be improved through regeneration (average dimension score below 3.0), the API returns a 422 error:

422 Response
{
  "error": "Content flagged as critically unsafe (avg score < 3.0). Cannot regenerate — requires human review.",
  "code": "RAIL_CRITICAL_CONTENT",
  "requires_human_review": true,
  "credits_consumed": 1.0,
  "evaluation": {
    "rail_score": {
      "score": 2.4,
      "confidence": 0.49,
      "summary": "RAIL Score: 2.4/10 — Critical"
    },
    "dimension_scores": {
      "fairness":       { "score": 2.6, "confidence": 0.74 },
      "safety":         { "score": 1.0, "confidence": 0.58 },
      "reliability":    { "score": 3.3, "confidence": 0.23 },
      "transparency":   { "score": 3.0, "confidence": 0.56 },
      "privacy":        { "score": 1.0, "confidence": 0.59 },
      "accountability": { "score": 1.9, "confidence": 0.82 },
      "inclusivity":    { "score": 4.1, "confidence": 0.80 },
      "user_impact":    { "score": 2.0, "confidence": 0.07 }
    },
    "failing_dimensions": ["fairness", "safety", "reliability", "transparency", "privacy", "accountability", "user_impact"]
  }
}

Continue Endpoint

POST/railscore/v1/safe-regenerate/continue

Use this endpoint for client-side regeneration workflows. When the initial /safe-regenerate request returns status: "awaiting_regeneration", it includes a session_id and a rail_prompt with improvement instructions. Regenerate the content using your own model, then send the result here to continue the evaluation loop.

Sessions expire after 15 minutes. Expired sessions return a 410 error.

ParameterTypeRequiredDescription
session_idstringYesSession ID from the initial safe-regenerate response
regenerated_contentstringYesThe improved content generated by your model using the provided rail_prompt
Request
curl -X POST https://api.responsibleailabs.ai/railscore/v1/safe-regenerate/continue \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RAIL_API_KEY" \
  -d '{
    "session_id": "sess_abc123def456",
    "regenerated_content": "Based on these symptoms, consulting a healthcare professional is strongly recommended for proper diagnosis. Possible conditions include X, but only a qualified doctor can make an accurate assessment. Please do not self-medicate without professional guidance."
  }'

The response has the same shape as the initial /safe-regenerate response. If thresholds still aren't met and iterations remain, the response will include a new rail_prompt for the next round.

Error Codes

400Invalid content length, invalid mode, invalid thresholds
401Missing or invalid API key
402Insufficient credits
410Session expired (continue endpoint only — sessions last 15 minutes)
422Critical content that cannot be safely regenerated
429Rate limit exceeded
500Regeneration 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: 1.0 available, 7.0 required",
  "code": "INSUFFICIENT_CREDITS",
  "balance": 1.0,
  "required": 7.0
}
410 — Session Expired
{
  "error": "Session expired. Please start a new safe-regenerate request.",
  "code": "SESSION_EXPIRED"
}

See the Credits & Pricing page for detailed cost breakdown per iteration.