> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Use response healing for structured JSON

> Recover near-valid structured JSON outputs without widening schemas or hand-retrying malformed responses.

Use this recipe when your app needs strict JSON and models occasionally return output that is almost valid, but still breaks your parser.

## 1. Start with a structured response contract

Response healing is only useful when the request already asks for structured output.

Good triggers:

* `response_format.type = "json_object"`
* JSON schema style output
* one stable object shape used by multiple callers

Do not enable healing for open-ended prose requests.

## 2. Enable the plugin at the right layer

You can enable `response-healing` in three places:

1. workspace default plugin policy
2. preset plugin config
3. per-request `plugins`

Precedence is:

1. workspace
2. preset
3. request

Use preset defaults when one workflow consistently expects structured JSON.

## 3. Keep the model output narrow

Healing works best when the requested output shape is already constrained.

Recommended:

* one object, not multiple unrelated blobs
* explicit required keys
* deterministic temperature where possible
* no extra explanatory text requested outside the JSON payload

## 4. Know what response healing can and cannot do

The current healing path is deterministic and non-streaming only. Streaming requests skip response healing entirely.

It can repair:

* markdown code fences around JSON
* trailing commas
* missing safe closers
* bare object keys in otherwise recoverable objects

When you need a narrower policy, use `strict` mode. Strict mode only unwraps already-valid JSON from fences or surrounding text and skips the broader syntactic repair transforms.

When the request uses JSON Schema style output, healing also validates the recovered payload before rewriting it. The current validator covers common constraints such as:

* required keys
* basic scalar and container types
* enums and const values
* array bounds and `uniqueItems`
* string length, regex, and common formats such as `email`, `uri`, `uuid`, and `date-time`
* number bounds and `multipleOf`
* object property limits and `additionalProperties: false`

It does not:

* invent missing semantic fields
* guess business values
* rewrite arbitrary prose into valid data

## 5. Verify that the plugin actually ran

When healing runs, the request details should show plugin execution information.

Check:

* plugin id
* whether it attempted a transform
* whether the payload changed
* failure reason when the response was not recoverable
* whether the request was non-streaming when you expected healing to run

If the plugin never appears, verify the request, preset, or workspace policy actually enabled it.

## 6. Separate parser problems from content problems

If healing does not help, determine which class of failure you have:

1. malformed JSON that is still structurally close
2. schema-valid JSON with wrong fields
3. prose instead of JSON
4. truncated output because token limits are too low

Only case 1 is a good fit for response healing.

## 7. Roll it out gradually

1. enable healing on one preset with stable structured output
2. watch plugin execution metadata in logs
3. confirm recovered payloads match the expected schema
4. widen to similar presets only after the logs look clean

## 8. Choose the right mode

* Use `safe` when the workflow benefits from bounded syntactic cleanup such as trailing-comma removal or bare-key quoting.
* Use `strict` when the workflow should only accept already-valid JSON once wrappers are removed.
* Check the request details to confirm which mode actually ran.

## Related

* [Use response caching with presets](https://phaseo.app/docs/v1/cookbook/response-caching-with-presets.md)
* [Roll out presets and debug routing](https://phaseo.app/docs/v1/cookbook/preset-rollout-and-routing-debug.md)
* [TypeScript Agent SDK](https://phaseo.app/docs/v1/sdk-reference/typescript/agent-sdk.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.