# Proposal review and Safe evidence

Paths on this page are relative to <code>/api/liquidity-studio/v2</code>. Authentication and required headers vary by operation.

[API reference overview](/api-reference/overview/) · [OpenAPI download](/openapi/liquidity-operating-system-v2.openapi.json)

## Operations on this page

| Method | Path | Operation |
| --- | --- | --- |
| <code>GET</code> | <code>/proposals/{id}/review</code> | [getProposalWorkspaceReview](#getProposalWorkspaceReview) |
| <code>GET</code> | <code>/proposals</code> | [listProposals](#listProposals) |
| <code>POST</code> | <code>/proposals</code> | [createProposals](#createProposals) |
| <code>GET</code> | <code>/proposals/{id}</code> | [getProposals](#getProposals) |
| <code>GET</code> | <code>/proposals/{id}/comments</code> | [listProposalComments](#listProposalComments) |
| <code>POST</code> | <code>/proposals/{id}/comments</code> | [appendProposalComment](#appendProposalComment) |
| <code>POST</code> | <code>/proposals/{id}/decisions</code> | [decideProposal](#decideProposal) |
| <code>POST</code> | <code>/proposals/{id}/safe-submissions</code> | [registerProposalSafeSubmission](#registerProposalSafeSubmission) |
| <code>POST</code> | <code>/proposal-comparisons</code> | [compareProposals](#compareProposals) |

<a id="getProposalWorkspaceReview"></a>

## Read a resource-version-bound proposal review snapshot

`GET /proposals/{id}/review`

Operation ID: <code>getProposalWorkspaceReview</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>) **OR** OAuth bearer token with <code>proposals:read</code> (<code>serviceCredential</code>)

Requires current workspace membership and either an interactive session or proposals:read service scope. The required resourceVersion query binds the current proposal generation; stale versions fail with 412. Comments do not advance the proposal version, so reviewEvidenceHash separately binds the review snapshot. Internal approvals and verified historical Safe submissions grant no new execution authority.

**Service scope:** <code>proposals:read</code>. Session access and workspace roles are evaluated separately.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | Min length: <code>1</code>; Max length: <code>160</code> |
| <code>id</code> | path | Yes | <code>string</code> | — |
| <code>resourceVersion</code> | query | Yes | [Hash](/api-reference/schemas/hash/) | — |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Read a resource-version-bound proposal review snapshot | <code>application/json</code>: <code>object</code> |
| <code>default</code> | Invalid input, access denied, source/storage failure or deadline exceeded. Workspace authentication errors may use the shared API envelope; bounded route failures expose a message. Rate-limit responses may be plain text. | <code>application/json</code>: <code>object</code> |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ProposalWorkspaceReview](/api-reference/schemas/proposal-workspace-review/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>default</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="listProposals"></a>

## List decision workspaces

`GET /proposals`

Operation ID: <code>listProposals</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>) **OR** OAuth bearer token with <code>proposals:read</code> (<code>serviceCredential</code>)

**Service scope:** <code>proposals:read</code>. Session access and workspace roles are evaluated separately.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>cursor</code> | query | No | <code>string</code> | Opaque cursor returned in the previous response metadata. |
| <code>limit</code> | query | No | <code>integer</code> | Default: <code>50</code>; Minimum: <code>1</code>; Maximum: <code>100</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Latest tenant-isolated aggregate versions | <code>application/json</code>: <code>object</code> |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | Array of All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code> | — |
| <code>data&#91;&#93;.allOf&#91;2&#93;.payload</code> | Yes | [ProposalWorkspace](/api-reference/schemas/proposal-workspace/) | — |
| <code>meta</code> | Yes | <code>object</code> | Additional properties rejected |
| <code>meta.count</code> | Yes | <code>integer</code> | Minimum: <code>0</code> |
| <code>meta.hasMore</code> | Yes | <code>boolean</code> | — |
| <code>meta.nextCursor</code> | No | <code>string</code> | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="createProposals"></a>

## Create a decision packet with zero server-recorded approvals

`POST /proposals`

Operation ID: <code>createProposals</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>) **OR** OAuth bearer token with <code>proposals:prepare</code> (<code>serviceCredential</code>)

**Service scope:** <code>proposals:prepare</code>. Session access and workspace roles are evaluated separately.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>160</code> |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |

### Request body

Required: **yes**.

**<code>application/json</code>**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>payload</code> | Yes | [ProposalWorkspaceInput](/api-reference/schemas/proposal-workspace-input/) | — |
| <code>status</code> | No | [OperatingSystemRecordStatus](/api-reference/schemas/operating-system-record-status/) | — |
| <code>evidenceHashes</code> | No | Array of [Hash](/api-reference/schemas/hash/) | Max items: <code>256</code> |
| <code>reason</code> | Yes | <code>string</code> | Min length: <code>3</code>; Max length: <code>500</code> |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>201</code> | Append-only proposal created; approvals are admitted only through typed decision events | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Request attempted derived approval or Safe fields, or failed validation | No response body declared |
| <code>409</code> | Immutable strategy-admission evidence is unavailable or superseded | No response body declared |

**<code>201</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code> | — |
| <code>data.allOf&#91;2&#93;.payload</code> | Yes | [ProposalWorkspace](/api-reference/schemas/proposal-workspace/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="getProposals"></a>

## Get one decision workspaces aggregate

`GET /proposals/{id}`

Operation ID: <code>getProposals</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>) **OR** OAuth bearer token with <code>proposals:read</code> (<code>serviceCredential</code>)

**Service scope:** <code>proposals:read</code>. Session access and workspace roles are evaluated separately.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>id</code> | path | Yes | <code>string</code> | — |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current immutable aggregate version | <code>application/json</code>: <code>object</code> |
| <code>404</code> | Not found | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>ETag</code> | Yes | <code>string</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code> | — |
| <code>data.allOf&#91;2&#93;.payload</code> | Yes | [ProposalWorkspace](/api-reference/schemas/proposal-workspace/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="listProposalComments"></a>

## listProposalComments

`GET /proposals/{id}/comments`

Operation ID: <code>listProposalComments</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>) **OR** OAuth bearer token with <code>proposals:read</code> (<code>serviceCredential</code>)

**Service scope:** <code>proposals:read</code>. Session access and workspace roles are evaluated separately.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>id</code> | path | Yes | <code>string</code> | — |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Append-only comments | <code>application/json</code>: <code>object</code> |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | Array of [OperatingSystemEvent](/api-reference/schemas/operating-system-event/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="appendProposalComment"></a>

## appendProposalComment

`POST /proposals/{id}/comments`

Operation ID: <code>appendProposalComment</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>160</code> |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>id</code> | path | Yes | <code>string</code> | — |
| <code>If-Match</code> | header | Yes | <code>string</code> | Pattern: <code>^"&#91;^"&#92;&#92; &#93;+"$</code> |

### Request body

Required: **yes**.

**<code>application/json</code>**

[ProposalCommentRequest](/api-reference/schemas/proposal-comment-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>201</code> | Comment appended; supersession binds the exact prior comment artifact on this proposal | <code>application/json</code>: <code>object</code> |

**<code>201</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [OperatingSystemEvent](/api-reference/schemas/operating-system-event/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="decideProposal"></a>

## Append an internal approval or rejection to a current DRAFT/VALIDATED packet

`POST /proposals/{id}/decisions`

Operation ID: <code>decideProposal</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>160</code> |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>id</code> | path | Yes | <code>string</code> | — |
| <code>If-Match</code> | header | Yes | <code>string</code> | Pattern: <code>^"&#91;^"&#92;&#92; &#93;+"$</code> |

### Request body

Required: **yes**.

**<code>application/json</code>**

[ProposalDecisionRequest](/api-reference/schemas/proposal-decision-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Superseding proposal and immutable packet-bound decision event | <code>application/json</code>: <code>object</code> |
| <code>409</code> | Packet is terminal, expired, or the actor already approved this packet | No response body declared |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ProposalDecisionResult](/api-reference/schemas/proposal-decision-result/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="registerProposalSafeSubmission"></a>

## Resolve finalized/reconciled issuer-Safe evidence server-side for an exact typed controller action

`POST /proposals/{id}/safe-submissions`

Operation ID: <code>registerProposalSafeSubmission</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>160</code> |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>id</code> | path | Yes | <code>string</code> | — |
| <code>If-Match</code> | header | Yes | <code>string</code> | Pattern: <code>^"&#91;^"&#92;&#92; &#93;+"$</code> |

### Request body

Required: **yes**.

**<code>application/json</code>**

[ProposalSafeSubmissionRequest](/api-reference/schemas/proposal-safe-submission-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Server-verified Safe transaction evidence registered; no execution performed by this route | <code>application/json</code>: <code>object</code> |
| <code>409</code> | Typed intent, signed release, current Safe, gateway evidence, finality, or reconciliation is unavailable/mismatched | No response body declared |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ProposalSafeSubmissionResult](/api-reference/schemas/proposal-safe-submission-result/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="compareProposals"></a>

## Build an immutable comparison hash for two to eight decision packets

`POST /proposal-comparisons`

Operation ID: <code>compareProposals</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>) **OR** OAuth bearer token with <code>proposals:prepare</code> (<code>serviceCredential</code>)

**Service scope:** <code>proposals:prepare</code>. Session access and workspace roles are evaluated separately.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>160</code> |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |

### Request body

Required: **yes**.

**<code>application/json</code>**

[ProposalComparisonRequest](/api-reference/schemas/proposal-comparison-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Deterministic proposal comparison | <code>application/json</code>: <code>object</code> |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ProposalComparison](/api-reference/schemas/proposal-comparison/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.