Skip to content

refactor: split openapi.json into 5 domain-specific specs #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 1 commit into from
Apr 9, 2026
Merged

refactor: split openapi.json into 5 domain-specific specs #121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion api-reference/accounts/add-artist.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Add Artist to Account'
openapi: 'POST /api/accounts/artists'
openapi: "/api-reference/openapi/accounts.json POST /api/accounts/artists"
---
2 changes: 1 addition & 1 deletion api-reference/accounts/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Create Account'
openapi: 'POST /api/accounts'
openapi: "/api-reference/openapi/accounts.json POST /api/accounts"
---
2 changes: 1 addition & 1 deletion api-reference/accounts/get.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Get Account'
openapi: 'GET /api/accounts/{id}'
openapi: "/api-reference/openapi/accounts.json GET /api/accounts/{id}"
---
2 changes: 1 addition & 1 deletion api-reference/accounts/id.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Get Account ID'
openapi: 'GET /api/accounts/id'
openapi: "/api-reference/openapi/accounts.json GET /api/accounts/id"
---
2 changes: 1 addition & 1 deletion api-reference/accounts/update.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Update Account'
openapi: 'PATCH /api/accounts'
openapi: "/api-reference/openapi/accounts.json PATCH /api/accounts"
---
2 changes: 1 addition & 1 deletion api-reference/admins/check.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Check Admin Status'
openapi: 'GET /api/admins'
openapi: "/api-reference/openapi/accounts.json GET /api/admins"
---
2 changes: 1 addition & 1 deletion api-reference/admins/coding-agent-slack-tags.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Coding Agent Slack Tags (Admin)'
openapi: 'GET /api/admins/coding/slack'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/coding/slack"
---
2 changes: 1 addition & 1 deletion api-reference/admins/coding-pr.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Get Coding Agent PR Merged Status (Admin)'
openapi: 'GET /api/admins/coding/pr'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/coding/pr"
---
2 changes: 1 addition & 1 deletion api-reference/admins/content-slack-tags.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Content Agent Slack Tags (Admin)'
openapi: 'GET /api/admins/content/slack'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/content/slack"
---
2 changes: 1 addition & 1 deletion api-reference/admins/emails.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Account Emails (Admin)'
openapi: 'GET /api/admins/emails'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/emails"
---
2 changes: 1 addition & 1 deletion api-reference/admins/privy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Privy Logins (Admin)'
openapi: 'GET /api/admins/privy'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/privy"
---
2 changes: 1 addition & 1 deletion api-reference/admins/sandboxes-orgs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Org Repo Stats (Admin)'
openapi: 'GET /api/admins/sandboxes/orgs'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/sandboxes/orgs"
---
2 changes: 1 addition & 1 deletion api-reference/admins/sandboxes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Account Sandboxes (Admin)'
openapi: 'GET /api/admins/sandboxes'
openapi: "/api-reference/openapi/accounts.json GET /api/admins/sandboxes"
---
2 changes: 1 addition & 1 deletion api-reference/apify/scraper.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Scraper Results'
openapi: 'GET /api/apify/scraper'
openapi: "/api-reference/openapi/social.json GET /api/apify/scraper"
---
2 changes: 1 addition & 1 deletion api-reference/artist/profile.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Artist Profile
openapi: GET /api/artist-profile
openapi: "/api-reference/openapi/releases.json GET /api/artist-profile"
---
2 changes: 1 addition & 1 deletion api-reference/artist/segments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Artist Segments
openapi: GET /api/artist/segments
openapi: "/api-reference/openapi/releases.json GET /api/artist/segments"
---
2 changes: 1 addition & 1 deletion api-reference/artist/socials.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Artist Socials
openapi: GET /api/artist/socials
openapi: "/api-reference/openapi/releases.json GET /api/artist/socials"
---
2 changes: 1 addition & 1 deletion api-reference/artists/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Create Artist'
openapi: 'POST /api/artists'
openapi: "/api-reference/openapi/releases.json POST /api/artists"
---
2 changes: 1 addition & 1 deletion api-reference/artists/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Get Artists'
openapi: 'GET /api/artists'
openapi: "/api-reference/openapi/releases.json GET /api/artists"
---
2 changes: 1 addition & 1 deletion api-reference/chat/artist.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: "Get Chat Artist"
openapi: GET /api/chats/{id}/artist
openapi: "/api-reference/openapi/research.json GET /api/chats/{id}/artist"
---
2 changes: 1 addition & 1 deletion api-reference/chat/chats.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Chats
openapi: GET /api/chats
openapi: "/api-reference/openapi/research.json GET /api/chats"
---
2 changes: 1 addition & 1 deletion api-reference/chat/compact.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Compact Chats'
openapi: 'POST /api/chats/compact'
openapi: "/api-reference/openapi/research.json POST /api/chats/compact"
---
2 changes: 1 addition & 1 deletion api-reference/chat/messages-copy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: "Copy Chat Messages"
openapi: POST /api/chats/{id}/messages/copy
openapi: "/api-reference/openapi/research.json POST /api/chats/{id}/messages/copy"
---
2 changes: 1 addition & 1 deletion api-reference/chat/messages-trailing-delete.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: "Delete Trailing Chat Messages"
openapi: "DELETE /api/chats/{id}/messages/trailing"
openapi: "/api-reference/openapi/research.json DELETE /api/chats/{id}/messages/trailing"
---
2 changes: 1 addition & 1 deletion api-reference/chat/messages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Chat Messages
openapi: GET /api/chats/{id}/messages
openapi: "/api-reference/openapi/research.json GET /api/chats/{id}/messages"
---
2 changes: 1 addition & 1 deletion api-reference/chat/segment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: "Get Chat Segment"
openapi: GET /api/chats/{id}/segment
openapi: "/api-reference/openapi/research.json GET /api/chats/{id}/segment"
---
2 changes: 1 addition & 1 deletion api-reference/comments/get.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Comments
openapi: GET /api/comments
openapi: "/api-reference/openapi/social.json GET /api/comments"
---
2 changes: 1 addition & 1 deletion api-reference/connectors/authorize.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Authorize Connector'
openapi: 'POST /api/connectors'
openapi: "/api-reference/openapi/social.json POST /api/connectors"
---
2 changes: 1 addition & 1 deletion api-reference/connectors/disconnect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Disconnect Connector'
openapi: 'DELETE /api/connectors'
openapi: "/api-reference/openapi/social.json DELETE /api/connectors"
---
2 changes: 1 addition & 1 deletion api-reference/connectors/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Connectors'
openapi: 'GET /api/connectors'
openapi: "/api-reference/openapi/social.json GET /api/connectors"
---
2 changes: 1 addition & 1 deletion api-reference/content-agent/callback.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Task Callback'
openapi: 'POST /api/content-agent/callback'
openapi: "/api-reference/openapi/content.json POST /api/content-agent/callback"
---
2 changes: 1 addition & 1 deletion api-reference/content-agent/webhook.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Slack Webhook'
openapi: 'POST /api/content-agent/{platform}'
openapi: "/api-reference/openapi/content.json POST /api/content-agent/{platform}"
---
2 changes: 1 addition & 1 deletion api-reference/content/analyze-video.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Analyze Video'
openapi: 'POST /api/content/analyze'
openapi: "/api-reference/openapi/content.json POST /api/content/analyze"
---
2 changes: 1 addition & 1 deletion api-reference/content/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Create Content'
openapi: 'POST /api/content/create'
openapi: "/api-reference/openapi/content.json POST /api/content/create"
---
2 changes: 1 addition & 1 deletion api-reference/content/edit.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Edit Content'
openapi: 'PATCH /api/content'
openapi: "/api-reference/openapi/content.json PATCH /api/content"
---
2 changes: 1 addition & 1 deletion api-reference/content/estimate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Estimate Cost'
openapi: 'GET /api/content/estimate'
openapi: "/api-reference/openapi/content.json GET /api/content/estimate"
---
2 changes: 1 addition & 1 deletion api-reference/content/generate-caption.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Generate Caption'
openapi: 'POST /api/content/caption'
openapi: "/api-reference/openapi/content.json POST /api/content/caption"
---
2 changes: 1 addition & 1 deletion api-reference/content/generate-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Generate Image'
openapi: 'POST /api/content/image'
openapi: "/api-reference/openapi/content.json POST /api/content/image"
---
2 changes: 1 addition & 1 deletion api-reference/content/generate-video.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Generate Video'
openapi: 'POST /api/content/video'
openapi: "/api-reference/openapi/content.json POST /api/content/video"
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Verify that each path-prefixed openapi frontmatter entry resolves to an existing operation.
python - <<'PY'
import json, pathlib, re, sys

errors = []
for mdx in pathlib.Path("api-reference").rglob("*.mdx"):
    text = mdx.read_text(encoding="utf-8")
    m = re.search(r'^openapi:\s*["\'](.+?)["\']\s*$', text, re.M)
    if not m:
        continue
    value = m.group(1).strip()
    if not value.startswith("/api-reference/openapi/"):
        continue
    parts = value.split(" ", 2)
    if len(parts) != 3:
        errors.append(f"{mdx}: malformed openapi value: {value}")
        continue
    spec_path, method, route = parts
    spec_file = pathlib.Path(spec_path.lstrip("/"))
    if not spec_file.exists():
        errors.append(f"{mdx}: missing spec file {spec_file}")
        continue
    spec = json.loads(spec_file.read_text(encoding="utf-8"))
    op = spec.get("paths", {}).get(route, {}).get(method.lower())
    if op is None:
        errors.append(f"{mdx}: operation not found in {spec_file}: {method} {route}")

if errors:
    print("\n".join(errors))
    sys.exit(1)

print("All path-prefixed openapi references resolve to existing operations.")
PY

Repository: recoupable/docs

Length of output: 127

🌐 Web query:

Mintlify docs: Is openapi: "/api-reference/openapi/.json METHOD /path"a supported API reference MDX frontmatter format, or should it remainopenapi: "METHOD /path"when usingopenapi.source+directory in docs config?

💡 Result:

Yes—Mintlify supports prefixing the operation with an OpenAPI file path in MDX frontmatter:

  • Supported: openapi: "/path/to/spec.json GET /users" (useful when you have multiple specs or need to disambiguate). [1]
  • Also supported: openapi: "GET /endpoint" (when Mintlify can resolve the operation against the default/available spec context). [2]

Using api.openapi in docs.json (including the { source, directory } form) defines what specs are available, but it doesn’t make the “<spec>.json METHOD /path” form invalid—include the spec path when you need to target a specific spec; otherwise keep it as METHOD /path. [1] [3]

Update openapi frontmatter format to match repo convention

The current format openapi: "/api-reference/openapi/content.json POST /api/content/video" works and references resolve correctly, but it deviates from the established repo guideline requiring openapi: 'METHOD /path' (without the spec file path prefix). Standardize to the documented format to maintain consistency across the codebase.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/content/generate-video.mdx` at line 3, The frontmatter key
openapi in api-reference/content/generate-video.mdx currently includes the spec
file path prefix; update the value to follow the repo convention by setting
openapi to the HTTP method and path only (e.g., openapi: 'POST
/api/content/video') so it matches the documented format used across the
codebase.

---
2 changes: 1 addition & 1 deletion api-reference/content/template-detail.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Get Template Detail'
openapi: 'GET /api/content/templates/{id}'
openapi: "/api-reference/openapi/content.json GET /api/content/templates/{id}"
---
2 changes: 1 addition & 1 deletion api-reference/content/templates.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'List Templates'
openapi: 'GET /api/content/templates'
openapi: "/api-reference/openapi/content.json GET /api/content/templates"
---
2 changes: 1 addition & 1 deletion api-reference/content/transcribe-audio.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Transcribe Audio'
openapi: 'POST /api/content/transcribe'
openapi: "/api-reference/openapi/content.json POST /api/content/transcribe"
---
2 changes: 1 addition & 1 deletion api-reference/content/upscale.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Upscale Content'
openapi: 'POST /api/content/upscale'
openapi: "/api-reference/openapi/content.json POST /api/content/upscale"
---
2 changes: 1 addition & 1 deletion api-reference/content/validate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Validate Artist'
openapi: 'GET /api/content/validate'
openapi: "/api-reference/openapi/content.json GET /api/content/validate"
---
2 changes: 1 addition & 1 deletion api-reference/fans/get.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Get Artist Fans
openapi: GET /api/fans
openapi: "/api-reference/openapi/releases.json GET /api/fans"
---
2 changes: 1 addition & 1 deletion api-reference/image/generation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Generate Image'
openapi: 'GET /api/image/generate'
openapi: "/api-reference/openapi/content.json GET /api/image/generate"
---
2 changes: 1 addition & 1 deletion api-reference/instagram/comments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Comments'
openapi: 'GET /api/instagram/comments'
openapi: "/api-reference/openapi/social.json GET /api/instagram/comments"
---
2 changes: 1 addition & 1 deletion api-reference/instagram/profiles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Profiles'
openapi: 'GET /api/instagram/profiles'
openapi: "/api-reference/openapi/social.json GET /api/instagram/profiles"
---
2 changes: 1 addition & 1 deletion api-reference/notifications/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Send Notification'
openapi: 'POST /api/notifications'
openapi: "/api-reference/openapi/accounts.json POST /api/notifications"
---
Loading