---
title: "Retire Previous Library"
method: POST
path: "/marketing/guidelines/documents/{file_id}/retire-previous-library"
tags: ["marketing-guidelines"]
---

# Retire Previous Library

`POST /marketing/guidelines/documents/{file_id}/retire-previous-library`

## Request

- Base URL: `https://api.kobaltlabs.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kobaltlabs.com/marketing/guidelines/documents/{file_id}/retire-previous-library`
- Auth: none declared

Retire what is left of this document's older library, now that a read one is in force.

The counterpart of pairing an approval with the one rule it replaces. That is the right move for a
handful of rules and the wrong one for a standards document with four hundred: bulk-approving a
read library leaves the older one live beside it, so the same obligation is checked twice, in two
wordings, and the library's counts stop meaning anything.

**Older library** is decided by provenance, not by dates: a requirement whose reading carried an
`agent_run_id` belongs to the current one, and everything else — the libraries the retired
per-document press wrote, and the rules written against a set by no reading at all — is the previous
one. A date comparison would need to guess where the boundary between two libraries falls;
provenance is the boundary.

**Refused until at least one read rule is in force.** Without that guard this empties a document's
library whenever it is pressed with nothing approved, which is the one outcome nobody could want:
no obligations checked, no error, and the only sign is a count going to zero. Approving something
first is also what makes the press meaningful — there is a replacement to retire *in favour of*.

Archived rules are left alone, by `supersede_requirements`: an archive is a person saying this
obligation does not apply, it is not in force either way, and overwriting it with "something
replaced this" is the one fact in that table nobody may overwrite.

## Path parameters

- `file_id` string, uuid, required

## Response `200`

Successful Response

- RetirePreviousLibraryResponse: What retiring a document's previous library actually retired. `retired_with_human_edits` is the part worth reporting back rather than only counting: those are requirements somebody reworded, re-scoped or wrote guidance for, and none of that work carries onto the rules that replace them. The retired revisions stay readable either way — this is an archival state change, not a delete — so the number is there for the surface to say what was given up, not to undo it.
  - `retired` integer, required
  - `retired_with_human_edits` integer, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-02** `425d5b8a3c17`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kobaltlabs/apis/kobaltlabs-api/changes/marketing/guidelines/documents/:file_id/retire-previous-library/post.md)

---

[API](https://skmtc.dev/kobaltlabs/apis/kobaltlabs-api.md) - [All operations](https://skmtc.dev/kobaltlabs/apis/kobaltlabs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kobaltlabs/apis/kobaltlabs-api/revisions/8587332d5e43?raw)