Videfy

Videfy Documentation Audit

The Videfy docs are a small set of user-facing how-to pages bolted onto a Mintlify scaffold whose developer surfaces (API reference, changelog, page slugs) were never finished — the "OpenAPI spec" is still the stock Plant Store sample, the ChatGPT MCP guide ships at /untitled-page, and the MCP URLs are missing their protocol scheme.

1. The published OpenAPI spec is the Mintlify Plant Store sample (critical)

Location: https://docs.videfy.ai/api-reference/openapi.json (referenced from llms.txt as the project's OpenAPI surface)

Problem: The file Videfy lists in llms.txt under "OpenAPI Specs" returns the stock Mintlify starter content:

"title": "OpenAPI Plant Store",
"description": "A sample API that uses a plant store as an example…",
"servers": [{ "url": "http://sandbox.mintlify.com" }],
"paths": { "/plants": …, "/plants/{id}": … },
"webhooks": { "/plant/webhook": … }

There is no Videfy API, no Videfy server URL, no Videfy schemas — just the template. The /api-reference index page itself 404s, so there is no human-readable API documentation either.

Consequence: Any AI agent (Claude, Cursor, Copilot) that discovers Videfy via llms.txt and follows the OpenAPI link will be told Videfy is a plant store with a /plants endpoint on sandbox.mintlify.com. Human developers looking for real API documentation hit a 404. There is no way to programmatically discover any Videfy endpoint.

The fix: Either (a) ship a real Videfy OpenAPI document and remove the placeholder, or (b) remove the OpenAPI link from llms.txt and the /api-reference route entirely until a real spec exists. Shipping a "Plant Store" under a real product domain is worse than shipping nothing.

2. ChatGPT MCP guide is published at /untitled-page (critical)

Location: https://docs.videfy.ai/untitled-page (titled "ChatGPT MCP connection" in llms.txt)

Problem: The ChatGPT MCP connection guide is live at the literal slug untitled-page. The llms.txt entry confirms it:

- [ChatGPT MCP connection](https://docs.videfy.ai/untitled-page.md)

The page itself is complete, but the URL is the Mintlify default placeholder that was never renamed.

Consequence: The canonical URL for one of two integration guides is unmemorable, unshareable in support channels, and signals to anyone evaluating the docs that they were never proofread. Search engines and agent indexers see a slug with zero topical signal. A future rename will break any existing links.

The fix: Rename the route to something like /chatgpt-mcp-connection to match the sibling /claude-mcp-connection. Add a 301 redirect from /untitled-page. Update llms.txt.

3. MCP connection URLs are missing the protocol scheme (critical)

Location: /claude-mcp-connection Step 2, and /untitled-page Step 3

Problem: Both MCP setup guides instruct users to register Videfy with this URL:

URL: app.videfy.ai/mcp

There is no https:// prefix. The Claude custom connector form and ChatGPT's custom MCP app form both require a fully qualified URL with scheme.

Consequence: A user (or an agent following the docs verbatim) who pastes app.videfy.ai/mcp will either get rejected at the form, or worse, have the client default to http://, which the MCP endpoint will refuse. This is the single instruction that makes the integration work; getting it wrong breaks the entire setup.

The fix: Change the documented URL to https://app.videfy.ai/mcp in both guides and in any in-product copy.

4. MCP integration docs omit auth, scopes, revocation, and error recovery (critical)

Location: /claude-mcp-connection (5 steps), /untitled-page (6 steps)

Problem: Both MCP guides walk through the click-path to connect (Open Connectors → Add Videfy → Connect → ask "Who am I on Videfy?" → start working) but never document:

• What authentication flow runs when you click "Connect" (OAuth? token paste? SSO?)
• What scopes/permissions the connector receives ("create stories, scenes, prompts, assets, and videos" is mentioned only as capabilities, not as a permission scope)
• How to revoke access
• What workspace the MCP acts on if the user belongs to multiple
• What the MCP tools are actually named or what arguments they accept
• What to do when something fails (Who am I on Videfy? returns nothing, Connect rejects, the connector isn't listed for your workspace beyond the "ask your admin" line)

Consequence: A developer evaluating whether to grant Claude or ChatGPT access to their Videfy workspace cannot answer basic security questions ("what can this connector do? how do I disconnect it?"). An agent connected via MCP has no documented tool surface, so prompting it requires guessing tool names. When the integration fails, neither user nor agent has a documented next step.

The fix: Add an "Authentication & Permissions" section to both MCP pages covering the auth flow, the scopes granted, how to revoke, and how workspace selection works. Publish the MCP tool catalog (names, parameters, return shapes) so agents and users can reason about what's available. Add a short "Troubleshooting" section for the common failure cases.

5. The three "how to start a video" flow names contradict each other across pages (significant)

Location: /getting-started §2.1 vs. /create-your-story

Problem: Both pages describe the same three-way choice at project creation, with different names:

/getting-started calls them:

• Idea
• Voiceover script
• Scene Flow

/create-your-story calls them:

• Idea or Prompt
• Narration Script
• Scene-by-Scene Breakdown

Then the /create-your-story subsections immediately switch again to "Voiceover Script" and "Scene Flow" as button labels.

Consequence: A user reading both pages — or an agent indexing them — sees three different vocabularies for the same selector. "Is 'Narration Script' the same option as 'Voiceover script'?" is a question the docs force the reader to answer themselves. Agents asked "how do I start a narration-based video" will give inconsistent answers depending on which page they retrieved.

The fix: Pick one canonical name per flow (presumably matching the in-product button label) and use it everywhere — including the picker description, both how-to pages, and llms.txt titles.

6. "Export" is positioned as the canonical workflow endpoint but has no documentation page (significant)

Location: /welcome ("from idea to export"), /getting-started → "What's Next?"

Problem: The Welcome page positions export as the end of the documented workflow ("walk through every stage of the Videfy workflow, from idea to export"), and the Getting Started guide ends with:

Use Export from the top panel Download or publish your final video

There is no Export page in llms.txt, no entry in the docs index, and no further explanation of formats, resolutions, publish destinations, watermarking, or credit costs for export.

Consequence: The documented happy path stops one click before the user actually ships a video — even though Welcome bills the docs as covering "idea to export." Questions every user has — "what resolutions can I export? does export cost credits? where does 'publish' go?" — have no answer in the docs.

The fix: Add an /export (or similar) page covering supported formats, resolution/quality settings, publish destinations, credit cost (if any), and download behavior. Link to it from the Welcome overview and the Getting Started "What's Next?" section.

7. Pricing and credit docs contain zero numbers (significant)

Location: /ai-generation-credits, /add-ons

Problem: Both pages describe credits and add-ons qualitatively without a single number anywhere:

"Images use credits per generated image" "Longer videos use more credits" "Add-Ons are one-time purchases that give you extra AI Generation Credits"

There is no credit cost per image, per video-second, per voiceover-character, per subtitle-minute. There is no add-on pack size, no price, no expiry policy, no refund terms, no model-specific cost table. The page says "Before generating, Videfy shows the credit cost where available" — i.e. the only place pricing is documented is inside the running product.

Consequence: A developer or finance owner cannot estimate cost before signing up or before scripting a workflow. An agent asked "how much will it cost to generate a 60-second video with model X" has no way to answer from the docs. Add-on purchasers have no documented expiry, so they don't know whether unused credits roll forever or evaporate.

The fix: Publish a credit-cost table per content type and per supported model, plus an add-on pack-size/price/expiry table. If pricing varies, document the formula and the range. Even a "credits per second of video for each model" matrix would be a step change.

8. Model Picker filter example references categories that aren't filters (significant)

Location: /pick-up-a-model → "Open and Use Model Filters"

Problem: The page says the filter tabs are exactly two: Style and Provider. Selection rules confirm: "Style: single selection only / Provider: multiple selections allowed." Then the very next sentence gives this example:

"You can combine multiple filters (for example: Text-to-Image + Leonardo + 16:9) to find the right model faster."

"Text-to-Image" and "16:9" are not Style or Provider values — they look like task and aspect-ratio filters that don't exist according to the docs.

Consequence: A user follows the example, can't find a "Text-to-Image" or "16:9" tab, and concludes either the docs are wrong or the feature is broken. An agent generating instructions from this page will hallucinate filter categories that the UI doesn't have.

The fix: Either remove the misleading example or — if Task and Aspect Ratio really are filters — list them in the tab inventory and selection-rules section so the page is internally consistent.

9. Galleries page contains an unresolved Markdown link (critical)

Location: /galleries → §10 "Gallery Access via the Left Side Menu"

Problem: The page says:

"For more detailed information on using the Gallery in Video Studio, see this article: [Video Studio Gallery]."

The square-bracketed text is a Markdown link with no URL — it was never resolved. The target page exists at /video-studio-gallery, but the link was never wired up, so a published documentation page contains a literally broken cross-reference.

Consequence: The bridge between the two Gallery pages is broken. Readers don't get the deep-link the page promises; agents parsing the Markdown see literal [Video Studio Gallery] text with no href and can't follow the cross-reference at all. This is the same failure mode as a 404 link, except invisible to standard link checkers because there's no URL to check.

The fix: Replace [Video Studio Gallery] with [Video Studio Gallery](/video-studio-gallery). Audit the rest of the docs for the same unresolved-bracket pattern.

10. The Storyboard Gallery's tab inventory is never documented (significant)

Location: /galleries vs. /video-studio-gallery

Problem: /video-studio-gallery explicitly lists five tabs for the Video Studio Gallery: Images, Videos, Animations, Overlays, Audio. /galleries references a "Storyboard Gallery" and a menu-level Gallery and tells the reader to click "the Gallery tab", but never enumerates what tabs the Storyboard Gallery contains. The reader has no way to tell whether Storyboard offers the same five tabs, a subset, or something different.

Consequence: Users asking "where do I find overlays — Storyboard or Video Studio?" have to guess. Agents asked the same question will either default to the only inventory documented (Video Studio's five tabs) or admit they don't know — both outcomes are bad when one of those Gallery surfaces is the more common entry point.

The fix: On /galleries, explicitly state the Storyboard Gallery's tab inventory and call out the differences from Video Studio Gallery ("Storyboard Gallery: X, Y; Video Studio Gallery adds Animations, Overlays, Audio") so the two surfaces are clearly distinguishable.

11. ChatGPT MCP guide tells the reader to skip Step 3 (minor)

Location: /untitled-page Step 2

Problem: Step 2 reads: "If Videfy is listed, select it and continue to Step 4." So the happy path is Step 1 → 2 → 4 → 5 → 6, and Step 3 ("Add Videfy manually") is only reached by a branch.

Consequence: Linear step numbering with a "jump to Step 4" branch is brittle: it breaks screen-readers, breaks translation tooling that renumbers lists, and breaks any agent that counts steps to estimate progress. A user who misses the branch instruction reads Step 3 as the next required action and adds Videfy as a custom app even when it was already listed.

The fix: Replace numbered steps with explicit branches: a "Videfy is listed" path and a "Videfy is not listed" path, each with its own short ordered list. Or move the manual-add path into a collapsible "If Videfy isn't listed" subsection so the linear step count stays continuous.

12. Supported video formats list omits .webm and .avi (minor)

Location: /compatible-file-types-for-upload → "Supported Video Formats"

Problem: The supported-video-formats list is only .mp4, .mov, .mkv, .wmv. .webm (the standard open web video container, used by every browser's recording API) and .avi (still common for legacy uploads) are both absent, and the page doesn't note whether their absence is by design or simply undocumented.

Consequence: A user dragging in a .webm export from OBS, a browser-recorder, or a screen-capture tool gets an unexplained upload failure with no way to tell from the docs whether the format is unsupported or whether they hit a bug. Same for .avi from legacy archives.

The fix: If .webm and .avi are supported, add them. If they're not, say so explicitly and recommend a conversion target.

13. Home Screen page documents almost nothing (minor)

Location: /home-screen

Problem: The Home Screen page is ~75 words of body content. It says the Home Screen is your dashboard, lists four bullet actions (view, open, create, manage with sub-bullets "Duplicate / Rename / Delete"), and stops. There is no documentation of project filtering, sorting, search, sharing, recent-vs-archived state, what "Manage projects" actually opens, what metadata is shown per project, or how the dashboard scales past a handful of projects.

Consequence: The page documents one of the central daily surfaces of the product as if it were a placeholder. Users wanting to know "can I search across my projects?" or "how do I share one?" get nothing. Agents indexing this page have almost no signal to surface against home-screen questions.

The fix: Expand /home-screen to cover the actual capabilities of the Dashboard: filtering, sorting, search, sharing if any, project metadata displayed, archive/trash state, and what each menu action does (including any irreversible behavior on Delete).

14. Subtitles page promises "three options" but lists four; heading levels skip a step (minor)

Location: /subtitles §1 and §5

Problem: Two internal inconsistencies on the same page:

• §5 "Delete a Subtitle" opens with "you have three options" and then numbers four items (Context Menu, Delete Key, Backspace Key, Delete All).
• §1 numbers Step 1 as #### (h4) and Step 2 as ### (h3) — the heading level jumps between adjacent steps.

Consequence: The "three options" miscount makes the reader recount and second-guess the doc. The heading-depth jump is worse than comprehension friction: Mintlify's auto-TOC and most agent chunkers infer page structure from heading depth, so a single #### → ### jump produces a malformed step list in two downstream systems at once.

The fix: Either change "three options" to "four options" or move "Delete All Subtitles" into its own subsection (it's arguably a different action). Normalize the §1 step headings to the same level so the auto-TOC and chunker output is correct.

15. No changelog, no version markers, no last-updated metadata (minor)

Location: Sitewide; canonical /changelog 404s

Problem: The Mintlify default /changelog route returns 404. None of the 13 pages listed in llms.txt carries a "last updated" date, a version tag, or any release-note surface. The docs offer no way to tell which features are new, which are deprecated, or when an instruction was last reviewed.

Consequence: Returning users can't tell what changed. Agents can't disambiguate stale content. Support has no shared vocabulary ("the export flow as of March 2026") to refer to.

The fix: Publish a /changelog page (Mintlify supports this natively) with dated entries. Add last-updated frontmatter to each page and surface it in the page footer.

What they do well

• llms.txt is published and lists every page — agents can discover the doc surface without scraping the navigation HTML.
• Upload size limits are concrete and parseable (1024 MB / 100 MB / 25 MB), and audio/image format lists are usefully broad.
• The MCP integration guides, despite the URL bug and step-skip flow, are blessedly short and step-numbered — the right shape for a setup task.

Top 3 recommendations

1. Replace the placeholder OpenAPI file or delete the link. Shipping the Mintlify Plant Store sample at docs.videfy.ai/api-reference/openapi.json is the single most damaging finding — it actively misleads any agent that follows llms.txt.
2. Fix the MCP setup blockers: add https:// to the connector URLs, rename /untitled-page, document auth/scopes/revocation, and add a short troubleshooting section. These are the highest-leverage pages because they're the entry point for agent users.
3. Reconcile the contradictions: unify the three flow names (Idea / Voiceover / Scene Flow) across pages, document the Storyboard Gallery's tab inventory so it can be compared to Video Studio's, fix the unresolved [Video Studio Gallery] Markdown link, and either correct or remove the "Text-to-Image + 16:9" Model Picker example. Then publish a credit-cost table so the pricing pages contain at least one number.