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

Header	Required	Value
`Authorization`	Yes	`Bearer sk_live_xxxxx`
`Content-Type`	Yes	`application/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

Tier	Limit	Overage
Free	1K repairs/month	Degraded service
Pro	100K repairs/month	Degraded service
Team	1M 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

Getting Started

Guides

Concepts

API Reference

SDKs

Migration

Batch Repair Endpoint

POST /v1/repair

Request

Headers

Body

Parameters

Response

Fields

Examples

Basic Repair

With Schema Validation

Failed Repair

Error Codes

Rate Limits

Next Steps

Streaming Endpoints

Response Object

Error Codes

TypeScript SDK

​POST /v1/repair

​Request

​Headers

​Body

​Parameters

​Response

​Fields

​Examples

​Basic Repair

​With Schema Validation

​Failed Repair

​Error Codes

​Rate Limits

​Next Steps

Streaming Endpoints

Response Object

Error Codes

TypeScript SDK

POST /v1/repair

Request

Headers

Body

Parameters

Response

Fields

Examples

Basic Repair

With Schema Validation

Failed Repair

Error Codes

Rate Limits

Next Steps