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

# Patch history and file view API

> Protocol methods for exact patch steps, file history, bounded diffs, and authorized workspace file viewing.

Patch history lets clients inspect filesystem changes without treating a provider's last event as an exact record. The gateway reports authority, provenance, exactness, coverage, and filesystem observation state with every history view.

See [Patch history and file mutation](https://docs.getpioneer.dev/architecture/patch-history.md) for the native mutation and recovery model.

## Methods

| Method | Params | Result | Purpose |
| - | - | - | - |
| `thread/patch_steps/page` | `ThreadPatchStepsPageParams` | `ThreadPatchStepsPageResponse` | Page applied patch steps across the visible thread execution scope. |
| `thread/file_patch_history/page` | `ThreadFilePatchHistoryPageParams` | `ThreadFilePatchHistoryPageResponse` | Page changes to one path across the visible thread execution scope. |
| `turn/patch_steps/page` | `TurnPatchStepsPageParams` | `TurnPatchStepsPageResponse` | Page native or provider-reported patch steps for one turn. |
| `turn/patch_record/get` | `TurnPatchRecordGetParams` | `TurnPatchRecordGetResponse` | Load one selected durable patch record. |
| `turn/patch_diff/get` | `TurnPatchDiffGetParams` | `TurnPatchDiffGetResponse` | Render a bounded unified diff for one turn and selection. |
| `thread/file/view_grant/create` | `ThreadFileViewGrantCreateParams` | `ThreadFileViewGrantCreateResponse` | Create a short-lived HTTP view URL for an authorized workspace text file. |

Patch history reads are authorized against the source thread, turn, execution scope, and resolved workspace path. The gateway limits page records, compressed and decompressed bytes, and diff bytes.

## Coverage fields

`PatchHistoryQueryCoverage` contains:

| Field | Values |
| - | - |
| `exactness` | `engine_verified`, `provider_reported`, or `incomplete`. |
| `exact` | `true` only when the selected view is exact. |
| `coverage` | `engine_verified_steps`, `provider_reported_steps`, `aggregate_only`, `incomplete`, or `untracked`. |
| `filesystem` | `pending`, `complete`, or `incomplete`. |
| `first_missing_ordinal` | Optional first missing commit ordinal. |

Use these fields when labeling a diff. A provider aggregate can be useful while still being less exact than a native engine record.

## History views

The `view` field identifies `timeline`, `turn_aggregate`, or `record_diff`. A thread file history entry includes its source execution context, environment id, turn id, invocation id, ordinal, and one file change. A turn step includes the full record and coverage for that query.

Cursors are opaque protocol objects. Thread file cursors contain environment, turn, ordinal, sequence, source thread, and commit timestamp fields. Restart pagination without a cursor when the cursor lacks the source thread or commit time required by the current scope.

## Patch record and diff selection

Patch records expose authority, provenance, exactness, outcome, content-addressed before and after snapshots, change kind, source and destination paths, and side effects. Change kinds are `add`, `replace`, `update`, `delete`, and `move`.

`turn/patch_record/get` accepts a typed selector for a turn record. `turn/patch_diff/get` accepts a selection and an optional `max_bytes`, capped by the gateway. The response contains the exactness, coverage, filesystem status, unified patch, rendered record count, and the ordinal range represented by the diff.

## File view grant

The file viewer does not receive a raw path and read it locally. A client sends the thread, optional turn and item context, and the markdown link href to `thread/file/view_grant/create`:

```json theme={null}
{
  "method": "thread/file/view_grant/create",
  "params": {
    "threadId": "thr_000000000000000001",
    "turnId": "trn_000000000000000001",
    "itemId": "itm_000000000000000001",
    "href": "src/main.rs:42"
  }
}
```

The response contains a relative `/storage/views/...` URL, expiry, file name, content type, byte size, and optional line and column. The gateway resolves and authorizes the workspace path. Text files are bounded to 10 MiB and are not silently truncated.

The client uses the relative URL with the authenticated gateway base URL. The grant is short lived and tied to the session and resolved file scope. A browser or system viewer receives only this grant URL, not a durable bearer credential.

## Related protocol surfaces

* [Turns API](https://docs.getpioneer.dev/protocol/turns.md) explains turn work and permission admission.
* [Threads API](https://docs.getpioneer.dev/protocol/threads.md) explains thread authorization and timeline reads.
* [Artifacts API](https://docs.getpioneer.dev/protocol/artifacts.md) covers durable uploaded files, which use a different storage identity.
* [Authentication and access API](https://docs.getpioneer.dev/protocol/auth.md) explains session and capability checks.

## Generated schemas

The coverage, step, and file-history types are nested in the response schemas and are not emitted as standalone files. The generated method schemas are:

* `/schemas/thread_patch_steps_page_params.json`
* `/schemas/thread_patch_steps_page_response.json`
* `/schemas/thread_file_patch_history_page_params.json`
* `/schemas/thread_file_patch_history_page_response.json`
* `/schemas/turn_patch_steps_page_params.json`
* `/schemas/turn_patch_steps_page_response.json`
* `/schemas/turn_patch_record_get_params.json`
* `/schemas/turn_patch_record_get_response.json`
* `/schemas/turn_patch_diff_get_params.json`
* `/schemas/turn_patch_diff_get_response.json`
* `/schemas/thread_file_view_grant_create_params.json`
* `/schemas/thread_file_view_grant_create_response.json`


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