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
✓ Yes
✗ No
Repeats up to max_regenerations (1–5) times
Credits consumed:
basic=1cr, deep=3cr per eval
- 1.Your content is evaluated across RAIL dimensions using the specified mode (basic or deep).
- 2.If any dimension scores fall below thresholds, the server generates an improvement prompt and regenerates the content.
- 3.The regenerated content is re-evaluated. This loop continues until thresholds pass or max iterations are reached.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | Text to evaluate and regenerate (10 – 10,000 characters) |
| mode | string | No | One of: "basic" or "deep". Default: "basic" |
| max_regenerations | integer | No | Maximum regeneration iterations (1–5). Default: 3 |
| thresholds | object | No | Threshold configuration (see below) |
| context | string | No | Additional context for evaluation (max 1,000 chars) |
| domain | string | No | Content domain. One of: general, healthcare, finance, legal |
| weights | object | No | Custom dimension weights (must sum to 100.0) |
| policy_hint | string | No | Additional policy guidance for regeneration |
Thresholds Object
| Field | Type | Default | Description |
|---|---|---|---|
| overall.score | float | 7.0 | Minimum overall RAIL score to pass |
| overall.confidence | float | 0.5 | Minimum confidence to accept score |
| tradeoff_mode | string | priority | One of: priority, strict, weighted |
| max_dimension_failures | integer | 2 | Max dimensions allowed to fail before regeneration |
| dimensions | object | — | Per-dimension threshold overrides (e.g., {"safety": 8.0}) |
Tradeoff Modes
| Mode | Behavior |
|---|---|
| priority | Dimensions with custom thresholds must pass individually. Other dimensions only need to meet the overall threshold. Best for focusing on specific dimensions. |
| strict | ALL dimensions must pass their threshold individually. Most rigorous — use for high-stakes content. |
| weighted | The weighted average across dimensions must pass. Individual dimensions can be below threshold as long as the overall score is sufficient. |
Request Example
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
{
"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
}
}{
"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.status | passed or max_iterations_reached |
| result.best_content | The highest-scoring version of the content |
| result.best_iteration | Which iteration produced the best content (0 = original) |
| result.original_content | The original input content |
| result.best_scores | RAIL scores for the best iteration: rail_score, dimension_scores, thresholds_met |
| result.iteration_history | Array of per-iteration results with failing dimensions and score improvement |
| credits_breakdown | Breakdown 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:
{
"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
/railscore/v1/safe-regenerate/continueUse 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| session_id | string | Yes | Session ID from the initial safe-regenerate response |
| regenerated_content | string | Yes | The improved content generated by your model using the provided rail_prompt |
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
400 | Invalid content length, invalid mode, invalid thresholds |
401 | Missing or invalid API key |
402 | Insufficient credits |
410 | Session expired (continue endpoint only — sessions last 15 minutes) |
422 | Critical content that cannot be safely regenerated |
429 | Rate limit exceeded |
500 | Regeneration failed |
Error Response Examples
{
"error": "Content must be between 10 and 10000 characters",
"code": "VALIDATION_ERROR"
}{
"error": "Invalid or missing API key",
"code": "AUTHENTICATION_ERROR"
}{
"error": "Insufficient credits: 1.0 available, 7.0 required",
"code": "INSUFFICIENT_CREDITS",
"balance": 1.0,
"required": 7.0
}{
"error": "Session expired. Please start a new safe-regenerate request.",
"code": "SESSION_EXPIRED"
}See the Credits & Pricing page for detailed cost breakdown per iteration.