refactor: content primitive docs — generic params, verb-qualifier routes, edit endpoint by sidneyswift · Pull Request #96 · recoupable/docs

sidneyswift · 2026-04-02T10:02:19Z

Summary

Full docs update to match the content primitive restructure.

Cleaned up Getting Started sidebar (removed misplaced items, merged duplicate groups)
Removed all fal.ai/FAL_KEY provider references from descriptions
Added security blocks (apiKeyAuth + bearerAuth) to all content endpoints
Renamed all content primitive paths to verb-qualifier pattern
Replaced render with edit endpoint (operations array + template mode)
Added analyze-video endpoint docs
Made all schemas generic (reference_image_url, audio_url, topic, audio_urls, model)

Summary by CodeRabbit

Documentation
- Added API reference pages for: Analyze Video; Edit Content; Generate Caption; Generate Image; Generate Video; Transcribe Audio; Upscale Content.
- Updated API reference navigation to reorganize Content and Posts sections for improved discoverability.

New endpoints documented: - POST /api/content/create/image — AI image generation - POST /api/content/create/video — image-to-video (or lipsync) - POST /api/content/create/text — LLM on-screen text - POST /api/content/create/audio — Whisper transcription - POST /api/content/create/render — ffmpeg final render (async) - POST /api/content/create/upscale — image/video upscaling Includes OpenAPI schemas, MDX pages, and navigation updates. Made-with: Cursor

…dpoints - Remove Create Content and Create Sandbox from Getting Started sidebar - Merge Posts and Post groups into single Posts group - Remove all fal.ai/FAL_KEY references from endpoint descriptions - Add security blocks (apiKeyAuth + bearerAuth) to all content endpoints Made-with: Cursor

Video analysis endpoint with request/response schemas, security blocks, MDX page, and nav entry in the Content group. Made-with: Cursor

Matches the API route rename — analysis is not content creation. Made-with: Cursor

Renamed all content primitive paths in openapi.json, MDX files, and docs.json nav to match the API route restructure. Made-with: Cursor

- Renamed all music-specific params in openapi.json schemas - Added model param to image, video, audio schemas - Replaced render path/schemas with edit (operations array + template mode) Made-with: Cursor

coderabbitai · 2026-04-02T10:02:27Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9ac32633-bf61-4116-99be-3860235cfb6e

📥 Commits

Reviewing files that changed from the base of the PR and between 3c69c63 and 933f184.

📒 Files selected for processing (7)

api-reference/content/analyze-video.mdx
api-reference/content/edit.mdx
api-reference/content/generate-caption.mdx
api-reference/content/generate-image.mdx
api-reference/content/generate-video.mdx
api-reference/content/transcribe-audio.mdx
api-reference/openapi.json

✅ Files skipped from review due to trivial changes (6)

api-reference/content/edit.mdx
api-reference/content/transcribe-audio.mdx
api-reference/content/generate-image.mdx
api-reference/content/analyze-video.mdx
api-reference/content/generate-caption.mdx
api-reference/content/generate-video.mdx

📝 Walkthrough

Walkthrough

Added seven new API reference MDX pages under api-reference/content/ (analyze-video, edit, generate-caption, generate-image, generate-video, transcribe-audio, upscale) and updated docs.json to include these entries and adjust Getting Started and Posts navigation.

Changes

Cohort / File(s)	Summary
Content API documentation `api-reference/content/analyze-video.mdx`, `api-reference/content/edit.mdx`, `api-reference/content/generate-caption.mdx`, `api-reference/content/generate-image.mdx`, `api-reference/content/generate-video.mdx`, `api-reference/content/transcribe-audio.mdx`, `api-reference/content/upscale.mdx`	Added seven new MDX pages. Each file contains frontmatter with a `title` and an `openapi` mapping to the respective `POST /api/content/...` (or `PATCH /api/content/video` for edit) endpoint.
Docs navigation `docs.json`	Updated navigation: removed some Getting Started API references, reorganized Posts grouping, and added the seven new Content API entries under API reference → Content.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

docs: add Content API endpoints (create, status, templates, validate,… #44 — Adds new api-reference/content MDX pages and updates docs.json navigation for Content API pages.
docs: add caption_length, upscale, and batch params to POST /api/content/create #54 — Modifies docs navigation for content-related API pages and updates related content endpoint docs.

Poem

🐰 I hopped through docs with whiskers bright,
Seven tiny pages set just right,
Titles tucked in YAML, endpoints in view,
A cheerful nibble — new docs for you! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately captures the main changes: refactoring content primitive documentation with verb-qualifier route naming, generic parameters, and an edit endpoint. It aligns well with the file summaries showing new MDX pages and docs.json restructuring.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feature/content-primitive-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Generate Image, Generate Video, Generate Caption, Transcribe Audio, Upscale Media — titles were still showing old "Create X" names. Made-with: Cursor

coderabbitai

🧹 Nitpick comments (1)

docs.json (1)
124-129: Minor path inconsistency: posts/ vs post/

The Posts group now contains paths with inconsistent naming: api-reference/posts/get (plural) and api-reference/post/comments (singular). Consider renaming the file/path for consistency in a follow-up.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs.json` around lines 124 - 129, The docs.json Pages array contains
inconsistent path names: "api-reference/posts/get" (plural) and
"api-reference/post/comments" (singular); pick a consistent convention (e.g.,
plural "posts") and rename the mismatched entry (e.g., change
"api-reference/post/comments" to "api-reference/posts/comments") so all
API-reference paths in the Posts group use the same resource naming; update any
corresponding filenames/routes to match the new path.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs.json`:
- Around line 124-129: The docs.json Pages array contains inconsistent path
names: "api-reference/posts/get" (plural) and "api-reference/post/comments"
(singular); pick a consistent convention (e.g., plural "posts") and rename the
mismatched entry (e.g., change "api-reference/post/comments" to
"api-reference/posts/comments") so all API-reference paths in the Posts group
use the same resource naming; update any corresponding filenames/routes to match
the new path.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 60da677b-f3c2-4e44-a7bc-008df24e002e

📥 Commits

Reviewing files that changed from the base of the PR and between c6913b3 and 5c74338.

📒 Files selected for processing (9)

api-reference/content/analyze-video.mdx
api-reference/content/edit.mdx
api-reference/content/generate-caption.mdx
api-reference/content/generate-image.mdx
api-reference/content/generate-video.mdx
api-reference/content/transcribe-audio.mdx
api-reference/content/upscale.mdx
api-reference/openapi.json
docs.json

Description now says "generate a video" not "generate from an image". Schema updated: prompt added, image_url removed from required. Made-with: Cursor

Made-with: Cursor

Each description now explains what the endpoint does and what inputs it takes, written for a user with no prior context. Removed jargon, implementation details, and stale parameter references. Made-with: Cursor

Made-with: Cursor

6 modes documented with per-param descriptions explaining which mode uses which input. All Veo 3.1 params exposed. Made-with: Cursor

sweetmantech · 2026-04-02T19:51:50Z

api-reference/content/analyze-video.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Analyze Video'
+openapi: 'POST /api/content/analyze-video'


KISS - why not simply POST /api/content/analyze?

Suggested change

openapi: 'POST /api/content/analyze-video'

openapi: 'POST /api/content/analyze'

sweetmantech · 2026-04-02T19:52:34Z

api-reference/content/edit.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Edit Content'
+openapi: 'POST /api/content/edit'


KISS - why not simpler?

Suggested change

openapi: 'POST /api/content/edit'

openapi: 'PATCH /api/content/video'

sweetmantech · 2026-04-02T19:53:44Z

api-reference/content/generate-caption.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Generate Caption'
+openapi: 'POST /api/content/generate-caption'


KISS - why not simpler?

Suggested change

openapi: 'POST /api/content/generate-caption'

openapi: 'POST /api/content/caption'

sweetmantech · 2026-04-02T19:54:25Z

api-reference/content/generate-image.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Generate Image'
+openapi: 'POST /api/content/generate-image'


KISS - why not simpler?

Suggested change

openapi: 'POST /api/content/generate-image'

openapi: 'POST /api/content/image'

sweetmantech · 2026-04-02T19:55:35Z

api-reference/content/generate-video.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Generate Video'
+openapi: 'POST /api/content/generate-video'


KISS - why not simpler?

Suggested change

openapi: 'POST /api/content/generate-video'

openapi: 'POST /api/content/video'

sweetmantech · 2026-04-02T19:56:53Z

api-reference/content/transcribe-audio.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Transcribe Audio'
+openapi: 'POST /api/content/transcribe-audio'


KISS - why not simpler?

Suggested change

openapi: 'POST /api/content/transcribe-audio'

openapi: 'POST /api/content/transcribe'

Replace verb-heavy paths with RESTful resource names — let HTTP methods convey the action instead of encoding it in the path. - POST /api/content/analyze-video -> POST /api/content/analyze - POST /api/content/generate-caption -> POST /api/content/caption - POST /api/content/generate-image -> POST /api/content/image - POST /api/content/generate-video -> POST /api/content/video - POST /api/content/transcribe-audio -> POST /api/content/transcribe - POST /api/content/edit -> PATCH /api/content/video Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sidneyswift added 6 commits April 2, 2026 03:15

docs: add POST /api/content/create/analyze endpoint reference

344aa0e

Video analysis endpoint with request/response schemas, security blocks, MDX page, and nav entry in the Content group. Made-with: Cursor

fix: rename content/create/analyze to content/analyze in docs

8353f1b

Matches the API route rename — analysis is not content creation. Made-with: Cursor

refactor: rename content endpoint paths to verb-qualifier pattern

29a9c8a

Renamed all content primitive paths in openapi.json, MDX files, and docs.json nav to match the API route restructure. Made-with: Cursor

refactor: update docs for generic content primitives + edit endpoint

d023d89

- Renamed all music-specific params in openapi.json schemas - Added model param to image, video, audio schemas - Replaced render path/schemas with edit (operations array + template mode) Made-with: Cursor

sidneyswift requested a review from sweetmantech as a code owner April 2, 2026 10:02

fix: update MDX page titles to match verb-qualifier naming

5c74338

Generate Image, Generate Video, Generate Caption, Transcribe Audio, Upscale Media — titles were still showing old "Create X" names. Made-with: Cursor

coderabbitai bot reviewed Apr 2, 2026

View reviewed changes

sidneyswift added 7 commits April 2, 2026 11:16

fix: update generate-video docs — image_url optional, add prompt field

6a605aa

Description now says "generate a video" not "generate from an image". Schema updated: prompt added, image_url removed from required. Made-with: Cursor

fix: rewrite generate-video description for clarity

d189b15

Made-with: Cursor

fix: simplify generate-video description

dc740b0

Made-with: Cursor

fix: rewrite all content endpoint descriptions for clarity

30578d7

Each description now explains what the endpoint does and what inputs it takes, written for a user with no prior context. Removed jargon, implementation details, and stale parameter references. Made-with: Cursor

fix: drop 'media' from Edit and Upscale titles

e30b135

Made-with: Cursor

fix: rename Edit → Edit Content, Upscale → Upscale Content

3c69c63

Made-with: Cursor

feat: update generate-video docs with mode param and full schema

39a3819

6 modes documented with per-param descriptions explaining which mode uses which input. All Veo 3.1 params exposed. Made-with: Cursor

sweetmantech reviewed Apr 2, 2026

View reviewed changes

sweetmantech approved these changes Apr 2, 2026

View reviewed changes

sweetmantech merged commit c20e95f into main Apr 2, 2026
2 checks passed

This was referenced Apr 3, 2026

feat: content V2 docs — malleable-first architecture, templates optional #100

Open

fix: address PR #102 review feedback #103

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: content primitive docs — generic params, verb-qualifier routes, edit endpoint#96

refactor: content primitive docs — generic params, verb-qualifier routes, edit endpoint#96
sweetmantech merged 15 commits intomainfrom
feature/content-primitive-docs

sidneyswift commented Apr 2, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Apr 2, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

coderabbitai bot left a comment

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

sweetmantech Apr 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	openapi: 'POST /api/content/analyze-video'
	openapi: 'POST /api/content/analyze'

	openapi: 'POST /api/content/edit'
	openapi: 'PATCH /api/content/video'

	openapi: 'POST /api/content/generate-caption'
	openapi: 'POST /api/content/caption'

	openapi: 'POST /api/content/generate-image'
	openapi: 'POST /api/content/image'

	openapi: 'POST /api/content/generate-video'
	openapi: 'POST /api/content/video'

	openapi: 'POST /api/content/transcribe-audio'
	openapi: 'POST /api/content/transcribe'

Conversation

sidneyswift commented Apr 2, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

sweetmantech Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sidneyswift commented Apr 2, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Apr 2, 2026 •

edited

Loading