---
title: "Prepared opening API reference"
canonical_url: https://zentrik.ai/docs/api/prepared-opening
markdown_url: https://zentrik.ai/docs/api/prepared-opening.md
last_reviewed: 2026-11-01
---

# Prepared opening API reference

Choose up to three existing Insight/Idea pairs for a prepared workspace introduction. Order and product-area wording are presentation settings. Saving does not validate Insights, approve Ideas, edit evidence, reset onboarding or send invitations. The API key selects the workspace.

- Human reference: https://zentrik.ai/docs/api/prepared-opening
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/prepared-opening — Read the opening selection

Operation ID: `get-prepared-opening-selection`

Read the saved sequence before editing. Retain updatedAt for the next save.

Required API key scopes: `insights:read`, `ideas:read`

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The saved presentation selection and its update timestamp. selection is null when none is saved. | — |
| 403 | Scope required | Both Insight and Idea scopes for the requested operation are required. | — |

### Example response

```json
{
  "selection": {
    "productLabel": "areas",
    "entries": []
  },
  "updatedAt": "2026-11-01T00:00:00.000Z"
}
```

---

## PUT /external/v1/prepared-opening — Save the opening selection

Operation ID: `save-prepared-opening-selection`

Replace the sequence. Each pair must already be linked in this workspace, remain active and have supporting Evidence. Entries must use distinct native UUIDs. productLabel is products or areas. expectedUpdatedAt must equal the last read timestamp, or null for the first save. Empty entries restore automatic ranking. Re-read before retrying an uncertain save. Deleted, rejected, unlinked or unreadable pairs are omitted from the opening; when no pair remains usable, automatic ranking applies.

Required API key scopes: `insights:write`, `ideas:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `entries` | array | Yes | Up to three ordered objects containing insightId and ideaId UUIDs. Optional evidenceIds selects up to three distinct active Evidence quotations already linked to that Insight. |
| `productLabel` | string | Yes | products or areas; changes opening wording only. |
| `expectedUpdatedAt` | string \| null | Yes | Exact updatedAt from the last read; null if none exists. |

### Example request

```curl
curl -X PUT 'https://zentrik.ai/api/external/v1/prepared-opening' -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"productLabel":"areas","entries":[],"expectedUpdatedAt":null}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The saved presentation selection and its update timestamp. selection is null when none is saved. | — |
| 403 | Scope required | Both Insight and Idea scopes for the requested operation are required. | — |
| 400 | Invalid selection | Malformed, duplicate, foreign, inactive, unsupported or unlinked records. | — |
| 409 | Changed since read | Read the selection again and reconcile the edit. | — |

### Example response

```json
{
  "selection": {
    "productLabel": "areas",
    "entries": []
  },
  "updatedAt": "2026-11-01T00:00:00.000Z"
}
```