Document the ingest_video Context action

SI
5d ago
+45-3

Summary

Documents the new ingest_video action of POST /api/context in api-reference/openapi/context.json: an additive oneOf block (action const, url, idempotency_key, optional organization_id) whose description states that the saved record is an explicitly unresolved private video locator, that the uploading channel is never assumed to be the artist, performer or credited artist, that recording match, captions, language and media version remain distinct unresolved/uncollected/unknown gaps, and that no lyrics, recording, artist, roster or brand document is created or changed. Also points the ingest URL description at ingest_video for YouTube videos, lists the action in the operation description, notes in the 200 response that ingest_video returns the saved partial request without dispatching a workflow, and adds an ingestVideo request example. The frontmatter-only operate.mdx page and docs.json need no change.

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

Merge sequencing

docs → database → api → app. Sibling PRs for this ticket, recoupable/database#107 (migration 20261010213100_context_video_entry.sql) and recoupable/api#1019 (ingest_video action), all on branch claude/ctx-2131-youtube-video-entry. The documented action only works once both are released. Overlap: docs#358 (ticket #2118) rewrites the same one-line ingest → url description; whichever merges second needs a one-line reconciliation that keeps #358's album/playlist wording and adds "a single YouTube music video uses ingest_video".

Verification

  • Ran: python3 -c "import json;d=json.load(open('api-reference/openapi/context.json'));print('ok')" → ok; the parsed oneOf action list is ingest, ingest_video, read, brief, save_brief, read_brief.
  • grep -c '"const": "ingest_video"' api-reference/openapi/context.json → 1.
  • Red → green: not applicable to a documentation-only change; the JSON parse check and action-list check above are the acceptance checks.
  • Not verified: Mintlify rendering (npx mintlify@latest dev not run), hosted docs deployment, the live API behavior this documents (fixture-tested only in the API PR), production database.

Out of scope / known gaps

  • ingest_release, verify_release and the other saved-entry actions remain undocumented in this JSON (pre-existing gap, not widened here).
  • No documentation for a future verify_video step, captions/language retention or video attribution review, which are not implemented.

🤖 Generated with Claude Code