Document campaign brief channels and promoted links

SI
7d ago
+98-0

Summary

Adds the ingest_campaign_brief request variant to the shared POST /api/context OpenAPI reference. The variant documents the existing brief fields (name, goal, audience, start and end dates) plus the two fields this ticket adds. channels takes up to ten distinct names of 1–60 characters, such as X, radio or press, marked uniqueItems. promoted takes up to twenty distinct {request_id, subject_id} pairs that must already be saved in the same workspace, also marked uniqueItems.

The description states that:

  • promoted links are candidates only, never ownership, rights, roster membership or catalog interest;
  • promoted targets are only saved {request_id, subject_id} pairs, never URLs or files, and asset keys are rejected;
  • channel names that look like links (scheme URLs, URI schemes, www. hosts, and absolute, home or drive paths) are rejected; this is not a full URL or file detector, so a bare example.com/release or plan.pdf passes as a name, and channel names are never fetched or linked;
  • goal and audience stay free text;
  • records must be saved first through a Context ingest request; the variant does not name the artist, release or catalog ingest actions, because this spec does not document them yet;
  • only artist, recording, release and catalog subjects can be targets; every other kind, including video, is rejected;
  • a retry of a saved brief under the same idempotency_key returns the stored request even if a target request was cancelled later;
  • no site or plan is generated;
  • supplied-material inventory remains an explicit gap.

This is the contract for Done-when item 1 (channels and links to promoted records) and for the boundary tests in item 3.

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

Merge sequencing

docs → database → api → app. This docs PR merges first. Sibling PRs for this ticket are recoupable/database#108 (migration 20261010213800_context_campaign_brief_promoted_links.sql) and recoupable/api#1020, both on branch claude/ctx-2138-campaign-promoted-links. No app change is needed, and this PR does not depend on any open PR. The edit is one additive oneOf entry anchored after the ingest variant, which keeps conflicts with sibling docs PRs small.

Verification

  • Ran: python3 -c "import json;d=json.load(open('api-reference/openapi/context.json'));v=d['paths']['/api/context']['post']['requestBody']['content']['application/json']['schema']['oneOf'];assert any(x['properties']['action'].get('const')=='ingest_campaign_brief' for x in v);print('ok')" → ok. The oneOf now lists ingest, ingest_campaign_brief, read, brief, save_brief, read_brief. A follow-up check confirmed channels.uniqueItems, channels.items.minLength == 1 and promoted.uniqueItems. Re-run on head 7ade5fe: the JSON parses, the oneOf list is unchanged, the three checks still hold, and the variant no longer mentions ingest_artist.
  • Ran: git diff origin/main --stat → 1 file, 98 insertions (the final-review commit rewords four descriptions in place). No MDX or docs.json change: api-reference/context/operate.mdx already renders this operation.
  • Red → green: not applicable to a documentation-only change. The companion database and api PRs carry the tests that failed first and then passed.
  • Not verified: Mintlify rendering or preview (npx mintlify dev was not run); hosted docs deployment; hosted API behaviour; live providers; the production database.

Review follow-ups

  • Addressed: uniqueItems on both arrays; one-character channel names; the URL/file rule now names only channels and promoted targets.
  • Addressed (final review and cubic): the variant no longer points callers to actions missing from this oneOf; video is now among the rejected subject kinds; the channel description states the check catches obvious links only; the same-key retry behaviour from database#108 is documented.
  • Not adopted: adding ingest_campaign_brief to the operation-level sentence that lists the documented actions. That single JSON line is already being rewritten by at least five open sibling docs PRs (#364, #366, #367 and others), so a later consolidation should update it once.

Out of scope / known gaps

  • Supplied-material inventory (Done-when item 2), URL-based promoted links with provider verification, campaign planning and inspector rendering are not documented because they are not implemented.
  • No hosted or live verification of any kind.

🤖 Generated with Claude Code