Skip to main content

​
POST /v1/repair

Fix malformed JSON in a single request. Use this for complete LLM outputs where you have the full string. For token-by-token repair, use streaming endpoints.

​
Request

POST https://api.shim.so/v1/repair

​
Headers

HeaderRequiredValue
AuthorizationYesBearer sk_live_xxxxx
Content-TypeYesapplication/json

​
Body

{
  "raw_output": string,
  "schema": JSONSchema,     // Optional
  "mode": "strict" | "lenient"  // Optional, default: "strict"
}

​
Parameters

raw_output (string, required)
  • The malformed JSON string from your LLM
  • Max size: 5MB
  • Can include markdown fences, trailing commas, truncated objects
schema (JSONSchema, optional)
  • JSON Schema for validation and type coercion
  • Shim will coerce types ("30" → 30)
  • Detect missing required fields
  • Remove extra fields in strict mode
mode (string, optional)
  • "strict": Remove extra fields not in schema (default)
  • "lenient": Keep extra fields

​
Response

Always returns HTTP 200 with structured envelope. Check success field. 
{
  "success": boolean,
  "repaired": object | null,
  "metadata": {
    "confidence": "high" | "medium" | "low" | "n/a",
    "was_repaired": boolean,
    "output_valid_json": boolean,
    "syntax_repairs": RepairDetail[],
    "schema_repairs": RepairDetail[],
    "repairs_applied": RepairDetail[],
    "warnings": Warning[],
    "errors": RepairError[]
  }
}

​
Fields

success (boolean)
  • true: Repair succeeded, use repaired object
  • false: Unrecoverable error, check metadata.errors
repaired (object | null)
  • The fixed JSON object
  • null if repair failed
metadata.confidence (string)
  • "high": Only structural fixes (safe)
  • "medium": Schema repairs or warnings
  • "low": Ambiguous repairs, review carefully
  • "n/a": Reserved (not currently emitted; perfect input returns "high")
metadata.was_repaired (boolean)
  • true: Shim made changes
  • false: Input was already valid
metadata.syntax_repairs (array)
  • Structural fixes: missing brackets, trailing commas, markdown fences
  • Always safe
metadata.schema_repairs (array)
  • Type coercion, field validation
  • Review these if confidence is "medium" or "low"
metadata.warnings (array)
  • Non-critical issues
  • Repair succeeded but review recommended
metadata.errors (array)
  • Critical failures
  • Repair failed if this is non-empty

​
Examples

​
Basic Repair

cURL
curl -X POST https://api.shim.so/v1/repair \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_output": "{\"name\": \"John\", \"age\": 30"
  }'
Response
{
  "success": true,
  "repaired": {
    "name": "John",
    "age": 30
  },
  "metadata": {
    "confidence": "high",
    "was_repaired": true,
    "output_valid_json": true,
    "syntax_repairs": [
      {
        "type": "closed_object_bracket",
        "confidence": "high",
        "safe": true
      }
    ],
    "schema_repairs": [],
    "warnings": [],
    "errors": []
  }
}

​
With Schema Validation

cURL
curl -X POST https://api.shim.so/v1/repair \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_output": "{\"name\": \"John\", \"age\": \"30\"}",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "age": { "type": "number" }
      },
      "required": ["name", "age"]
    }
  }'
Response
{
  "success": true,
  "repaired": {
    "name": "John",
    "age": 30
  },
  "metadata": {
    "confidence": "medium",
    "was_repaired": true,
    "output_valid_json": true,
    "syntax_repairs": [],
    "schema_repairs": [
      {
        "type": "type_coercion",
        "confidence": "high",
        "safe": true,
        "field": "age",
        "original_value": "30",
        "repaired_value": 30
      }
    ],
    "warnings": [],
    "errors": []
  }
}

​
Failed Repair

cURL
curl -X POST https://api.shim.so/v1/repair \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_output": "not even close to JSON"
  }'
Response
{
  "success": false,
  "repaired": null,
  "metadata": {
    "confidence": "low",
    "was_repaired": false,
    "output_valid_json": false,
    "syntax_repairs": [],
    "schema_repairs": [],
    "warnings": [],
    "errors": [
      {
        "code": "UNRECOVERABLE_SYNTAX_ERROR",
        "message": "The JSON structure is too malformed to repair",
        "severity": "critical",
        "recoverable": false,
        "suggestion": "The JSON structure is too malformed to repair. Check LLM output."
      }
    ]
  }
}

​
Error Codes

See Error Codes Reference for full list. Common errors:
  • INVALID_REQUEST: Missing or invalid parameters
  • PAYLOAD_TOO_LARGE: Input exceeds 5MB
  • UNRECOVERABLE_SYNTAX_ERROR: JSON too malformed to repair
  • SCHEMA_VALIDATION_FAILED: Repaired JSON doesn’t match schema

​
Rate Limits

TierLimitOverage
Free1K repairs/monthDegraded service
Pro100K repairs/monthDegraded service
Team1M repairs/month$0.30/1K overage
See Rate Limits Guide for details.

​
Next Steps

Streaming Endpoints

Repair JSON token-by-token

Response Object

Full response schema

Error Codes

Complete error reference

TypeScript SDK

Use the official SDK