Skip to main content

​
CLAUDE.md — Legnext API Docs

Guidance for working in this repository.

​
What this is

The public API documentation for Legnext (the Midjourney API platform).
  • Tooling: Mintlify — config in docs.json (theme mint), content in .mdx.
  • Published to: https://docs.legnext.ai
  • Repo: github.com/legnext-ai/docs (origin/main). Mintlify auto-deploys on push to main.
  • ⚠️ This is the only live docs repo. github.com/leggiemint/docs (local ~/projects/API/docs) is a stale abandoned clone — do not edit it.

​
Structure

  • getting-started/ — overview, quickstart, models, image-parameters, video-parameters, output-storage, notice
  • api-reference/ — one .mdx per endpoint (image-generation, video-generation, enhancement, task-management, account-management)
  • sdk/ — per-language guides (csharp, go, java, javascript, php, python, ruby, rust)
  • integrations/ — make, n8n, postman
  • changelog.mdx, docs.json (navigation — nav is explicit; a file not listed here is not linked)

​
Preview & deploy

Deploy = push to main (Mintlify picks it up). Per global rules: don’t auto-push; prefer a new commit over amend.

​
Sources of truth (do not guess — verify)

  1. Parameter / version / model behavior → the backend: ~/projects/API/Legnext-backend/internal/task/mj_task/ (e.g. version.go for which flags each MJ version accepts) and the provider code under internal/standalone_server/mj/provider/.
  2. Midjourney’s own semantics → local scrape of MJ official docs in docs/midjourney-prompt/ (prompt-related articles, markdown + urls.txt manifest for re-scraping; reference only, never publish as-is). The old mirror at ~/projects/saas/midjourney/midjourney-official-docs/ no longer exists.
When backend and our docs disagree, the backend wins (it’s what actually runs). When our docs and MJ official docs disagree on MJ semantics, MJ official wins.

​
Known gotchas / lessons

  • API Reference fields are generated from openapi.yaml. Endpoint MDX files should contain only frontmatter plus intent, prerequisites, relationships, and common mistakes. Do not re-add hand-written headers, request/response tables, full JSON examples, or error-code lists: Mintlify already renders them from OpenAPI, and the duplicate layer previously drifted on Get Task auth, required fields, enums, and task IDs.
  • The Topaz-backed Enhancement API is suspended. Keep /v1/enhance-upscale in OpenAPI with its 503 maintenance response for existing callers, but do not add it back to public navigation or describe it as available. Midjourney /v1/upscale and /v1/enhance are different follow-up actions.
  • The image-parameters table is GENERATED. In getting-started/image-parameters.mdx, everything between the {/* BEGIN GENERATED:image-parameters-table */} and {/* END ... */} markers comes from spec/mj-image-params.yaml in legnext-ai/Legnext-backend — a backend CI job opens a sync PR here when the spec changes (KEH-286). Never hand-edit inside the markers (keep them intact); fix the YAML upstream instead. schemas/mj-image-params.v1.json is synced the same way and served at https://docs.legnext.ai/schemas/mj-image-params.v1.json — the public contract, additive-only within v1. Do not re-add hand-written parameter lists anywhere (incl. openapi.yaml); link to the schema URL.
  • --cref is NOT a v7+ parameter. It only works on v6 / v6.1 / niji 6. v7 replaced it with Omni Reference (--oref / --ow); v8.1 drops omni too. Our docs historically mislabeled this (v7 marked ✓ for --cref), which caused a real support ticket — keep the version-support matrix accurate against the backend + MJ official docs.
  • The default model version is v7 (no --v → runs as v7). A param valid only on v6.x will fail upstream with an opaque Invalid prompt format unless the user pins --v 6.1.
  • Keep --oref naming consistent (MJ calls it Omni Reference); avoid the old “Object Reference” / inconsistent “Universal Reference” labels.
  • mint dev can wedge on on-demand compiles (2026-08-10 incident). First hit on a new/changed page triggers a compile; repeated or parallel requests against it queue up and snowball until the node process pins at ~100% CPU and the whole server stops responding (all pages, not just the new one). Discipline:
    1. One request at a time against the dev server, with a generous --max-time — never re-fire or parallelize curls when one is hanging; each extra request makes the wedge worse.
    2. A hang → check before retrying: lsof -nP -iTCP:3000 -sTCP:LISTEN + ps for CPU. ~100% CPU = wedged → Ctrl+C and restart npx mint dev; do not keep poking a wedged server.
    3. To rule out content errors without the dev server, run npx mint validate (static full-build validation). Only suspect MDX syntax if validate fails.
    4. After restart, re-verify with a single curl per page (curl -s -o /dev/null -w "%{http_code}").