---
title: "Open a ledger subject"
description: "Requires a workspace-bound API key with ledger:write and an owner, admin, or member role. Appends a subject line with a class and no attributes: opening a row is not a finding. Names and identifiers arrive later as designators and claims. With entityId, the subject is anchored to that catalog entity. The entity kind must align with the class (for example, a vendor anchors an organization. A CVE anchors nothing). Send an Idempotency-Key header to make retries safe. A replay returns 200."
canonical: https://y2.dev/docs/api/reference/ontology-ledger/openLedgerSubjectV2/
---

Endpoint Reference[Ontology Ledger](https://y2.dev/docs/api/reference/ontology-ledger)

# Open a ledger subject

Requires a workspace-bound API key with ledger:write and an owner, admin, or member role. Appends a subject line with a class and no attributes: opening a row is not a finding. Names and identifiers arrive later as designators and claims. With entityId, the subject is anchored to that catalog entity. The entity kind must align with the class (for example, a vendor anchors an organization. A CVE anchors nothing). Send an Idempotency-Key header to make retries safe. A replay returns 200.

`POST https://api.y2.dev/api/v2/ledger/subjects`

- Operation ID: `openLedgerSubjectV2`
- Required scopes: `ledger:write`
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | No | Client-generated retry key retained for 24 hours. Repeating the same key and canonical JSON body returns the original resource. Changing the body returns `409 IDEMPOTENCY_CONFLICT`. |

## Request body

`application/json`: `LedgerSubjectCreateRequest` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `class` | `LedgerSubjectClass` | Yes | Subjects never change class. An assessment would be another claim. |
| `entityId` | string | No | Catalog entity to anchor the subject to. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Idempotent replay of an earlier open. | `LedgerSubjectCreatedResponse` |
| 201 | Subject opened. | `LedgerSubjectCreatedResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 404 | Resource not found |  |
| 409 | Resource conflict (e.g., webhook in use) |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | `LedgerSubjectSummary` |  |
| `data.id` | string |  |
| `data.type` | string |  |
| `data.class` | `LedgerSubjectClass` | Subjects never change class. An assessment would be another claim. |
| `data.label` | string or null | Value of the live preferred-label designator, or null. |
| `data.openedAt` | string (date-time) |  |
| `data.anchor` | `LedgerEntityAnchor` or null |  |