Response Object

All Shim endpoints return HTTP 200 with this structured envelope.

RepairResponse

interface RepairResponse {
  success: boolean;
  repaired: any | null;
  metadata: RepairMetadata;
}

Fields

success (boolean)

true: Repair succeeded, use repaired object
false: Unrecoverable error, check metadata.errors

repaired (any | null)

The fixed JSON object
null if repair failed
Type depends on input (object, array, primitive)

metadata (RepairMetadata)

Detailed information about the repair
See below for full schema

RepairMetadata

interface RepairMetadata {
  confidence: ConfidenceLevel;
  was_repaired: boolean;
  output_valid_json: boolean;
  syntax_repairs: RepairDetail[];
  schema_repairs: RepairDetail[];
  repairs_applied: RepairDetail[];  // Combined list
  warnings: Warning[];
  errors: RepairError[];
}

Fields

confidence (ConfidenceLevel)

"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")

was_repaired (boolean)

true: Shim made changes
false: Input was already valid

output_valid_json (boolean)

true: Repaired output is valid JSON
false: Repair failed, output is not valid JSON

syntax_repairs (RepairDetail[])

Structural fixes: brackets, commas, markdown fences
Always safe

schema_repairs (RepairDetail[])

Type coercion, field validation
Review these if confidence is "medium" or "low"

repairs_applied (RepairDetail[])

Combined list of all repairs
Includes both syntax and schema repairs

warnings (Warning[])

Non-critical issues
Repair succeeded but review recommended

errors (RepairError[])

Critical failures
Repair failed if this is non-empty

RepairDetail

interface RepairDetail {
  type: string;
  confidence: ConfidenceLevel;
  safe: boolean;
  original_value?: any;
  repaired_value?: any;
  field?: string;
}

Fields

type (string)

Repair type identifier
Examples: "closed_object_bracket", "type_coercion", "removed_extra_field"

confidence (ConfidenceLevel)

Confidence level for this specific repair
"high", "medium", or "low"

safe (boolean)

true: Safe to apply automatically
false: Review recommended

original_value (any, optional)

Original value before repair
Only present for schema repairs

repaired_value (any, optional)

Value after repair
Only present for schema repairs

field (string, optional)

Field name that was repaired
Only present for schema repairs

Warning

interface Warning {
  code: string;
  message: string;
  field?: string;
  severity: 'low' | 'medium' | 'high';
  suggestion?: string;
}

Fields

code (string)

Warning code identifier
Example: "EXTRA_FIELD_REMOVED"

message (string)

Human-readable warning message

field (string, optional)

Field that triggered warning

severity (‘low’ | ‘medium’ | ‘high’)

Warning severity level

suggestion (string, optional)

How to address the warning

RepairError

interface RepairError {
  code: string;
  message: string;
  field?: string;
  severity: 'critical' | 'high' | 'medium';
  recoverable: boolean;
  suggestion?: string;
}

Fields

code (string)

Error code identifier
See Error Codes

message (string)

Human-readable error message

field (string, optional)

Field that caused error

severity (‘critical’ | ‘high’ | ‘medium’)

Error severity level

recoverable (boolean)

true: Can retry
false: Unrecoverable, log and alert

suggestion (string, optional)

How to fix the error

Example Responses

Successful Repair

{
  "success": true,
  "repaired": {
    "name": "John",
    "age": 30
  },
  "metadata": {
    "confidence": "medium",
    "was_repaired": true,
    "output_valid_json": true,
    "syntax_repairs": [
      {
        "type": "closed_object_bracket",
        "confidence": "high",
        "safe": true
      }
    ],
    "schema_repairs": [
      {
        "type": "type_coercion",
        "confidence": "high",
        "safe": true,
        "field": "age",
        "original_value": "30",
        "repaired_value": 30
      }
    ],
    "repairs_applied": [
      {
        "type": "closed_object_bracket",
        "confidence": "high",
        "safe": true
      },
      {
        "type": "type_coercion",
        "confidence": "high",
        "safe": true,
        "field": "age",
        "original_value": "30",
        "repaired_value": 30
      }
    ],
    "warnings": [],
    "errors": []
  }
}

Failed Repair

{
  "success": false,
  "repaired": null,
  "metadata": {
    "confidence": "low",
    "was_repaired": false,
    "output_valid_json": false,
    "syntax_repairs": [],
    "schema_repairs": [],
    "repairs_applied": [],
    "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."
      }
    ]
  }
}

With Warnings

{
  "success": true,
  "repaired": {
    "name": "John",
    "age": 30
  },
  "metadata": {
    "confidence": "medium",
    "was_repaired": true,
    "output_valid_json": true,
    "syntax_repairs": [],
    "schema_repairs": [
      {
        "type": "removed_extra_field",
        "confidence": "medium",
        "safe": true,
        "field": "email"
      }
    ],
    "repairs_applied": [
      {
        "type": "removed_extra_field",
        "confidence": "medium",
        "safe": true,
        "field": "email"
      }
    ],
    "warnings": [
      {
        "code": "EXTRA_FIELD_REMOVED",
        "message": "Field 'email' not in schema, removed in strict mode",
        "field": "email",
        "severity": "medium",
        "suggestion": "Add 'email' to schema or use lenient mode"
      }
    ],
    "errors": []
  }
}

Next Steps

Batch Endpoint

API reference for batch repair

Streaming Endpoints

API reference for streaming repair

Error Codes

Complete error reference

TypeScript SDK

Use the official SDK

Getting Started

Guides

Concepts

API Reference

SDKs

Migration

Response Object

Response Object

RepairResponse

Fields

RepairMetadata

Fields

RepairDetail

Fields

Warning

Fields

RepairError

Fields

Example Responses

Successful Repair

Failed Repair

With Warnings

Next Steps

Batch Endpoint

Streaming Endpoints

Error Codes

TypeScript SDK

​Response Object

​RepairResponse

​Fields

​RepairMetadata

​Fields

​RepairDetail

​Fields

​Warning

​Fields

​RepairError

​Fields

​Example Responses

​Successful Repair

​Failed Repair

​With Warnings

​Next Steps

Batch Endpoint

Streaming Endpoints

Error Codes

TypeScript SDK

Response Object

RepairResponse

Fields

RepairMetadata

Fields

RepairDetail

Fields

Warning

Fields

RepairError

Fields

Example Responses

Successful Repair

Failed Repair

With Warnings

Next Steps