Streaming Repair Endpoints

Repair JSON token-by-token as it arrives from your LLM. No buffering delays. For complete outputs, use batch repair.

How Streaming Works

Start a session → Get a session_id
Push chunks → Send tokens as they arrive
Finalize → Get the repaired result

Sessions expire after 60 seconds of inactivity.

POST /v1/repair/stream/start

Start a new streaming session.

Request

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

Headers:

Header	Required	Value
`Authorization`	Yes	`Bearer sk_live_xxxxx`
`Content-Type`	Yes	`application/json`

Body:

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

Response

{
  "session_id": "sess_abc123",
  "expires_at": 1234567890000  // Unix timestamp (ms)
}

Example

cURL

curl -X POST https://api.shim.so/v1/repair/stream/start \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" }
      }
    }
  }'

Response

{
  "session_id": "sess_abc123",
  "expires_at": 1705780800000
}

POST /v1/repair/stream/push

Push a chunk to an active session.

Request

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

Headers:

Header	Required	Value
`Authorization`	Yes	`Bearer sk_live_xxxxx`
`Content-Type`	Yes	`application/json`

Body:

{
  "session_id": string,  // Required
  "chunk": string        // Required, max 5MB
}

Response

{
  "state": {
    "structurally_complete": boolean,
    "json_parseable": boolean,
    "safe_to_emit": boolean,
    "partial": object | null,
    "buffered": string,
    "incomplete_token": string,
    "brace_depth": number,
    "in_string": boolean,
    "expected_next": string[]
  }
}

State Fields:

structurally_complete: Braces balanced, not in string, no incomplete token
json_parseable: JSON.parse() will succeed
safe_to_emit: Safe to show to user (parseable + no critical issues)
partial: Parsed object (null if not parseable)
buffered: Current buffer content
incomplete_token: Held incomplete token (e.g., "0.")
brace_depth: Current nesting depth
in_string: Are we inside a string?
expected_next: Hints for what might come next

Example

cURL

curl -X POST https://api.shim.so/v1/repair/stream/push \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "chunk": "{\"name\": \"Jo"
  }'

Response

{
  "state": {
    "structurally_complete": false,
    "json_parseable": false,
    "safe_to_emit": false,
    "partial": null,
    "buffered": "{\"name\": \"Jo",
    "incomplete_token": "",
    "brace_depth": 1,
    "in_string": true,
    "expected_next": ["hn\"", "e\""]
  }
}

POST /v1/repair/stream/finalize

Finalize a session and get the repaired result.

Request

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

Headers:

Header	Required	Value
`Authorization`	Yes	`Bearer sk_live_xxxxx`
`Content-Type`	Yes	`application/json`

Body:

{
  "session_id": string  // Required
}

Response

Same as batch repair response.

{
  "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[],
    "warnings": Warning[],
    "errors": RepairError[]
  }
}

Example

cURL

curl -X POST https://api.shim.so/v1/repair/stream/finalize \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123"
  }'

Response

{
  "success": true,
  "repaired": {
    "name": "John"
  },
  "metadata": {
    "confidence": "high",
    "was_repaired": true,
    "output_valid_json": true,
    "syntax_repairs": [
      {
        "type": "closed_object_bracket",
        "confidence": "high",
        "safe": true
      }
    ],
    "schema_repairs": [],
    "warnings": [],
    "errors": []
  }
}

Complete Example

# 1. Start session
curl -X POST https://api.shim.so/v1/repair/stream/start \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

# Response: {"session_id": "sess_abc123", "expires_at": 1705780800000}

# 2. Push chunk 1
curl -X POST https://api.shim.so/v1/repair/stream/push \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "chunk": "{\"name\": \"Jo"
  }'

# 3. Push chunk 2
curl -X POST https://api.shim.so/v1/repair/stream/push \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "chunk": "hn\", \"age\": 30"
  }'

# 4. Finalize
curl -X POST https://api.shim.so/v1/repair/stream/finalize \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123"
  }'

# Response: {"success": true, "repaired": {"name": "John", "age": 30}, ...}

Error Codes

See Error Codes Reference for full list. Common errors:

SESSION_NOT_FOUND: Session expired or doesn’t exist
BUFFER_SIZE_EXCEEDED: Possible hallucination loop (circuit breaker)
SERVICE_UNAVAILABLE: Server at max capacity

Next Steps

Batch Endpoint

Fix complete JSON outputs

TypeScript SDK

Use the official SDK

Streaming Guide

Best practices for streaming

Error Codes

Complete error reference

Getting Started

Guides

Concepts

API Reference

SDKs

Migration

Streaming Repair Endpoints

Streaming Repair Endpoints

How Streaming Works

POST /v1/repair/stream/start

Request

Response

Example

POST /v1/repair/stream/push

Request

Response

Example

POST /v1/repair/stream/finalize

Request

Response

Example

Complete Example

Error Codes

Next Steps

Batch Endpoint

TypeScript SDK

Streaming Guide

Error Codes

​Streaming Repair Endpoints

​How Streaming Works

​POST /v1/repair/stream/start

​Request

​Response

​Example

​POST /v1/repair/stream/push

​Request

​Response

​Example

​POST /v1/repair/stream/finalize

​Request

​Response

​Example

​Complete Example

​Error Codes

​Next Steps

Batch Endpoint

TypeScript SDK

Streaming Guide

Error Codes

Streaming Repair Endpoints

How Streaming Works

POST /v1/repair/stream/start

Request

Response

Example

POST /v1/repair/stream/push

Request

Response

Example

POST /v1/repair/stream/finalize

Request

Response

Example

Complete Example

Error Codes

Next Steps