# Simulation studies and sharing

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>/studies</code> | [listStudies](#listStudies) |
| <code>POST</code> | <code>/studies</code> | [createStudies](#createStudies) |
| <code>GET</code> | <code>/studies/{id}</code> | [getStudies](#getStudies) |
| <code>GET</code> | <code>/study-shares</code> | [listStudyShares](#listStudyShares) |
| <code>GET</code> | <code>/study-shares/{id}</code> | [getStudyShares](#getStudyShares) |
| <code>POST</code> | <code>/sandbox/studies</code> | [runNonCustodialSandboxStudy](#runNonCustodialSandboxStudy) |
| <code>POST</code> | <code>/studies/{id}/share-links</code> | [createStudyShareLink](#createStudyShareLink) |
| <code>POST</code> | <code>/study-shares/{id}/revoke</code> | [revokeStudyShareLink](#revokeStudyShareLink) |
| <code>POST</code> | <code>/studies/{id}/reports</code> | [createSignedStudyReport](#createSignedStudyReport) |
| <code>GET</code> | <code>/studies/{id}/report-jobs</code> | [listStudyReportJobs](#listStudyReportJobs) |

<a id="listStudies"></a>

## List simulation studies

`GET /studies`

Operation ID: <code>listStudies</code>

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

**Service scope:** <code>studies: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 | [SimulationStudy](/api-reference/schemas/simulation-study/) | — |
| <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="createStudies"></a>

## Create simulation studies

`POST /studies`

Operation ID: <code>createStudies</code>

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

**Service scope:** <code>studies:write</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>**

[SimulationStudyRequest](/api-reference/schemas/simulation-study-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>201</code> | Append-only aggregate created | <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 | Exactly one of: All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code>; <code>object</code> | — |
| <code>data.oneOf&#91;1&#93;.allOf&#91;2&#93;.payload</code> | Yes | [SimulationStudy](/api-reference/schemas/simulation-study/) | — |
| <code>data.oneOf&#91;2&#93;.study</code> | Yes | All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code> | — |
| <code>data.oneOf&#91;2&#93;.study.allOf&#91;2&#93;.payload</code> | Yes | [SimulationStudy](/api-reference/schemas/simulation-study/) | — |
| <code>data.oneOf&#91;2&#93;.job</code> | Yes | [OperatingSystemJob](/api-reference/schemas/operating-system-job/) | — |
| <code>data.oneOf&#91;2&#93;.interactive</code> | Yes | Constant <code>false</code> | — |
| <code>data.oneOf&#91;2&#93;.signedReportPending</code> | Yes | Constant <code>true</code> | — |

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

<a id="getStudies"></a>

## Get one simulation studies aggregate

`GET /studies/{id}`

Operation ID: <code>getStudies</code>

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

**Service scope:** <code>studies: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 | [SimulationStudy](/api-reference/schemas/simulation-study/) | — |

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

<a id="listStudyShares"></a>

## List revocable simulation-study shares

`GET /study-shares`

Operation ID: <code>listStudyShares</code>

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

### 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 | [StudyShare](/api-reference/schemas/study-share/) | — |
| <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="getStudyShares"></a>

## Get one revocable simulation-study shares aggregate

`GET /study-shares/{id}`

Operation ID: <code>getStudyShares</code>

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

### 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 | [StudyShare](/api-reference/schemas/study-share/) | — |

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

<a id="runNonCustodialSandboxStudy"></a>

## Persist a deterministic non-custodial study with no execution authority

`POST /sandbox/studies`

Operation ID: <code>runNonCustodialSandboxStudy</code>

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

**Service scope:** <code>studies:write</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>**

[SandboxSimulationStudyRequest](/api-reference/schemas/sandbox-simulation-study-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>201</code> | Sandbox study and immutable evidence | <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 | <code>object</code> | Additional properties rejected |
| <code>data.study</code> | Yes | All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code> | — |
| <code>data.study.allOf&#91;2&#93;.payload</code> | Yes | [SimulationStudy](/api-reference/schemas/simulation-study/) | — |
| <code>data.sandbox</code> | Yes | Constant <code>true</code> | — |
| <code>data.custodyAuthorityGranted</code> | Yes | Constant <code>false</code> | — |
| <code>data.signingAuthorityGranted</code> | Yes | Constant <code>false</code> | — |
| <code>data.executionAuthorityGranted</code> | Yes | Constant <code>false</code> | — |
| <code>data.networkCodeExecuted</code> | Yes | Constant <code>false</code> | — |

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

<a id="createStudyShareLink"></a>

## Create a private expiring or issuer-approved public study link

`POST /studies/{id}/share-links`

Operation ID: <code>createStudyShareLink</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> | — |

### Request body

Required: **yes**.

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

[StudyShareRequest](/api-reference/schemas/study-share-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>201</code> | Revocable share link | <code>application/json</code>: <code>object</code> |
| <code>409</code> | Study is not completed or the permanent public slug is already claimed | 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 | [StudyShare](/api-reference/schemas/study-share/) | — |

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

<a id="revokeStudyShareLink"></a>

## Immediately revoke a private or public study share without deleting evidence

`POST /study-shares/{id}/revoke`

Operation ID: <code>revokeStudyShareLink</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>**

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

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <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>200</code> | Append-only revoked share version | <code>application/json</code>: <code>object</code> |
| <code>412</code> | Strong precondition failed | 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 | All of: [RecordEnvelope](/api-reference/schemas/record-envelope/); <code>object</code> | — |
| <code>data.allOf&#91;2&#93;.payload</code> | Yes | [StudyShare](/api-reference/schemas/study-share/) | — |

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

<a id="createSignedStudyReport"></a>

## Queue a signed JSON, PDF, and CSV report

`POST /studies/{id}/reports`

Operation ID: <code>createSignedStudyReport</code>

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

**Service scope:** <code>studies:write</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> | — |
| <code>id</code> | path | Yes | <code>string</code> | — |

### Request body

Required: **yes**.

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

[SignedStudyReportRequest](/api-reference/schemas/signed-study-report-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>202</code> | Fenced report job | <code>application/json</code>: <code>object</code> |

**<code>202</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 | <code>object</code> | Additional properties rejected |
| <code>data.job</code> | Yes | [OperatingSystemJob](/api-reference/schemas/operating-system-job/) | — |
| <code>data.source</code> | Yes | <code>object</code> | Additional properties rejected |
| <code>data.source.id</code> | Yes | <code>string</code> | Min length: <code>3</code>; Max length: <code>160</code> |
| <code>data.source.version</code> | Yes | <code>integer</code> | Minimum: <code>1</code> |
| <code>data.source.artifactHash</code> | Yes | [Hash](/api-reference/schemas/hash/) | — |

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

<a id="listStudyReportJobs"></a>

## List report job state and dead-letter evidence

`GET /studies/{id}/report-jobs`

Operation ID: <code>listStudyReportJobs</code>

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

**Service scope:** <code>studies: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> | Report jobs | <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 [OperatingSystemJob](/api-reference/schemas/operating-system-job/) | — |

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