Document unreleased recording and planned release intake

SI
5d ago
+191-2

Summary

Documents two new POST /api/context actions, ingest_unreleased_recording and ingest_planned_release, in api-reference/openapi/context.json. They let an account save an unreleased song or a planned release before it has an ISRC, UPC or store listing. The reference says that identifiers stay unknown, that caller-supplied identifiers are rejected, and that lifecycle, products/formats and promotional or pre-save links are stored apart from store IDs. An omitted lifecycle stays unknown for both entries. Referenced recordings must already be saved in the same workspace; they are checked when the request is first saved, so an identical replay returns the saved request. One recording may appear on several planned releases, at most once per release. The operation description and the 200 response describe the {request} these actions return: a partial request with explicit identifier gaps and no workflow dispatch. Only oneOf entries and descriptions changed; no MDX page or nav change is needed.

Refs recoupable/app#2141 (child of epic recoupable/app#2116).

Merge sequencing

docs (this PR) → database (recoupable/database#111) → api (recoupable/api#1023). This PR is additive and documents behavior that ships with the database migration and API change for this ticket.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" → parses. The /api/context oneOf lists ingest, read, brief, save_brief, read_brief, ingest_unreleased_recording, ingest_planned_release; release.required is ["title"]; promotional url has pattern ^https?://\S+$; recording_subject_ids has uniqueItems: true.
  • Review follow-up (head 16de026): the unreleased-music 200 sentence now follows the snapshot description instead of splitting it; links carry an explicit lowercase http(s) pattern; tracklist IDs are unique; release lifecycle_state is optional.
  • Red → green: not applicable (documentation only). The schemas match lib/context/unreleasedMusicOperationSchemas.ts in recoupable/api#1023: title 2–200 without control characters, lifecycle enums (omitted = unknown), at most 20 products and 20 lowercase http(s) links without whitespace, at most 100 unique recording subject IDs, and the shared idempotency key pattern.
  • Not verified: Mintlify render or broken-link check, hosted docs deployment, hosted API behavior, live providers and the production database.

Out of scope / known gaps

  • Assigning an ISRC, UPC or store ID to an internal recording or release later, and handling conflicting IDs, comes in a later slice of #2141.
  • No chat or inspector UI.
  • No provider lookup.

🤖 Generated with Claude Code