​

Prompt: Set up the Mintlify llms.txt + llms-full.txt workflow

Paste this whole file into a Claude Code session at the repo root. It is self-contained — the agent does not need this conversation’s history.

​

Goal

1. Are auto-generated from the OpenAPI spec and the docs.json navigation, not hand-maintained.
2. Follow the format conventions established in scripts/generate-llms-full.mjs and the current llms-full.txt (see “Format conventions” below).
3. Stay fresh automatically — regenerate on every change to api-v3/api-v3.yaml, docs.json, or any .mdx referenced in docs.json.
4. Override Mintlify’s default auto-generated versions, which group entries in an order we don’t want and produce flat, ungrouped indexes.

​

What already exists

• scripts/generate-llms-full.mjs — ESM Node script. Parses api-v3/api-v3.yaml, groups endpoints by tag, renders each one with a parameters table, curl example, recursive bullet-list response shape (with inline type signatures), and truncated example JSON. Emits warnings for missing credit costs, undocumented params, and missing 200 responses. Static HEADER / CONCEPTS / APPENDICES blocks frame the generated output. Single dep: yaml. Editorial knobs (credit costs, tag order, shape aliases, source-slug overrides) are in lookup tables at the top of the file. Read this file before changing anything.
• scripts/package.json — Just yaml and a build script.
• Makefile — make refresh-llms runs the generator. make verify-llms runs it and fails if the committed files would change (drift check for CI).
• llms-full.txt — current generated output. ~3,500 lines / ~115 KB, covers all 42 endpoints. Read enough of it to internalize the format.
• llms.txt — currently a hand-maintained index, ~100 lines. The workflow needs to start generating this too.

​

Why not use Mintlify’s auto-generated llms files

• The default llms.txt is one flat ## Docs list — no grouping by section (API reference vs. concepts vs. app guides vs. FAQs).
• Some entries have truncated descriptions ending in … mid-sentence.
• A few entries have no description at all.
• The default llms-full.txt doesn’t inline OpenAPI content — endpoints collapse to a /api-v3/api-v3.yaml get /path directive line that’s a dead pointer in a static text file.
• Mintlify components (<Tabs>, <Frame>, <Card>, etc.) leak through raw, breaking heading hierarchy.

​

Format conventions (treat as binding)

​

llms-full.txt

• One top-of-file orientation block: base URL, auth header, content type, pagination semantics, timestamp convention, country-code format, “no sandbox” warning, common response envelope. First ~30 lines.
• Endpoints grouped by tag in a fixed order: Instagram, TikTok, YouTube, Sponsor / Brand, Natural Language Search, Account.
• Each endpoint has: ### METHOD /path — Title heading, two-line meta block (Source: …md then Credits: N on the next line), one-paragraph purpose, parameters table (for simple query params) or bullet list (for complex schemas), curl example, recursive bullet-list response shape with inline type signatures (Claude-platform-docs style: - \field: type` with description on the next indented line, recursing into nested objects and array items down to a depth limit), truncated example JSON (arrays capped at 2 items +”… N more items”sentinel). Endpoints are separated by blank lines, **not**---` rules.
• Shape aliases (SHAPE_ALIASES map): TikTok and YouTube /audience endpoints reference Instagram’s instead of repeating identical shapes.
• Appendices at the end. The 250-row country-code table and 770-row industry list are linked out, not inlined.
• App user guides and FAQs are not included — those belong in a separate llms-full-app.txt if needed.

​

llms.txt

• Standard format: # Title, optional > tagline, then bulleted lists under H2 section headings.
• Group entries under named sections instead of one flat ## Docs:
  • ## API Reference — every endpoint, grouped by platform sub-bullets or sub-headings (Instagram, TikTok, YouTube, Sponsor, NLS, Account).
  • ## Concepts — auth, custom search filters, NL search guide, error codes, credit usage, quickstart, introduction.
  • ## Reference Tables — country codes, language codes, industry list, YT/IG categories.
  • ## OpenAPI Specs — link to canonical spec(s). Cull duplicates; the current file lists 5 ambiguously-named specs.
• Every entry has a non-empty description. Drop trailing … truncations — rewrite shorter or use the OpenAPI summary directly.
• URLs end in .md so an agent following them gets raw markdown, not HTML.

​

Tasks

1. Add scripts/generate-llms-index.mjs (or extend the existing generator — your call) that emits llms.txt. Pull endpoint titles and descriptions from api-v3/api-v3.yaml (reuse the spec parser already in generate-llms-full.mjs — factor it into a shared module if cleaner). Pull non-endpoint entries by walking docs.json and reading frontmatter title + description from each referenced .mdx. Skip pages tagged for the app/extension guides — those belong in a separate index if at all.
2. Update scripts/package.json with whatever new build script you add (e.g., build:full, build:index, build:all).
3. Update the Makefile so make refresh-llms regenerates both files. make verify-llms should fail on drift in either file.
4. Add a CI workflow (.github/workflows/llms-refresh.yml or similar) that:
   • Triggers on push to main affecting api-v3/api-v3.yaml, docs.json, or any .mdx under api-v3/ or api-reference/.
   • Runs make refresh-llms.
   • Commits the regenerated files back to the branch (or opens a PR if pushing to main directly is restricted — check the repo’s branch protection rules first).
   • On PRs (not push), runs make verify-llms instead of regenerating, so the PR fails fast when the committed files are stale.
5. Verify the override actually works. Mintlify’s deploy preview should serve the static llms.txt and llms-full.txt from the project root, not its auto-generated ones. Confirm by deploying a preview branch and curl-ing both URLs on the preview domain. If Mintlify ignores the static file, escalate — there may be a config flag in docs.json.

​

Constraints and traps

• Don’t change llms-full.txt output unless asked — current consumers (downstream LLM clients, possibly cached) depend on the format. If you refactor the generator, run make refresh-llms and confirm the diff is empty before committing.
• Don’t pull in heavy deps. The generator currently uses one (yaml) and Node built-ins. Stay there. No bundlers, no TypeScript build step.
• Keep the script ESM Node, plain .mjs. Matches the existing internal/ai-context/scripts/ convention.
• The existing Makefile has two targets that hardcode an absolute path to a different developer’s home (/Users/debbywang/...). Do NOT replicate that pattern — use relative paths from the Makefile’s directory.
• Path-with-space gotcha: this repo lives at …/API test/… (literal space). Bash cd and Make $(dir $(abspath ...)) need quoting / careful handling. Test on this exact path before declaring done.
• If docs.json references .mdx files that have no frontmatter, the current Mintlify build still works but llms.txt would have empty descriptions. Decide: either skip those pages, fail loudly, or use the first # H1 as a fallback. Pick the option that keeps the index honest.

​

How to verify when done

• make refresh-llms produces both files with a clean exit.
• make verify-llms exits 0 immediately after refresh-llms.
• git diff --stat after running shows updates in both files when the spec changes, none otherwise.
• The new llms.txt has section headings (## API Reference, etc.), every entry has a description, and URLs end in .md.
• llms-full.txt is byte-identical to the pre-change version unless you intentionally changed the format (and got sign-off).
• The CI workflow runs successfully on a test PR that modifies the spec.