docs(merge-queue): document the v2 Merge Queue API and a v1 migration guide, behind a hidden tab

[pv72895]

Documents the v2 Merge Queue API ahead of its release, with a guide for moving v1 integrations to it. The pages live in a tab marked "hidden": true, the same way Changelog works: they're in no navigation, but anyone with the URL can open them, so we can review before launch.

What's here

• openapi-v2.json is resynced from trunk2 main's ts/apps/public-api/openapi-v2.json (identical to it, as of trunk-io/trunk2#6512). That includes the API-key wording, the orgKey → apiKey scheme rename, and the prose fixes from #6511 and its review. The Flaky Tests v2 pages built from the same file pick up the new authentication text and scheme name, plus one new ErrorCode value; their operations are unchanged.
• docs.json adds the hidden "Merge Queue API v2" tab. It leads with the migration guide, then generates the 30 merge-queue operations under /merge-queue/reference/api-v2/…, split into Merge queues, Queue order, Pull requests, Testing, Impacted targets, Metrics and Repositories. Dynamic CI and Flaky Tests operations are left out.
• merge-queue/reference/api-v2.mdx is the landing page. It covers:
  • authentication with API keys (Settings → Developer → API Keys) and what each permission allows;
  • how to resolve IDs, pagination, errors, retrying writes and compatibility;
  • a card per endpoint.
• merge-queue/reference/api-v2/migrate-from-v1.mdx is the v1-to-v2 migration guide. It covers:
  • a copyable prompt for a coding agent, which reads the guide and each endpoint page as .md;
  • creating an API key, with a permissions table keyed by v1 calls;
  • an endpoint-by-endpoint map;
  • automation and dashboard examples;
  • the renames a port can't guess (pull request records, timelines, testing results, verification runs, settings);
  • behavior changes, and a checklist.
• merge-queue/reference/api-v2/github-actions.mdx covers uploading impacted targets from GitHub Actions with trunk-io/login, including pull requests from forks.

The v1 reference is untouched. The v2 pages never mention the legacy org API token, which is deprecated along with v1.

Before merging

• Nothing outstanding: trunk-io/trunk2#6511 and #6512 have both merged, and openapi-v2.json here matches trunk2 main. If the spec changes again before this merges, copy it over again.

At release

• Move the group into the Merge Queue tab next to the v1 "API reference", and delete the hidden tab.
• Release the Developer → API Keys settings page (SHOW_DEVELOPER_SETTINGS), which the authentication section and the migration guide send every reader to.
• Turn on the GitHub Actions login in production (GITHUB_ACTIONS_LOGIN_ENABLED and trunk-io/trunk#34100), release the Fork PR CI access setting, and tag trunk-io/login@v1. The GitHub Actions page depends on all three.
• Add a changelog entry, and link to v2 from the v1 page and setup-and-administration/apis.

Testing

• mint broken-links reports the same 12 broken links as main, and none from these pages.
• On the preview deployment: every v2 page, the migration guide and its .md version return 200. Every endpoint link and in-page anchor in the guide resolves. No visible text on any v2 page mentions an org token, and the API playground's credential picker reads apiKey.
• The migration guide was reviewed by an agent porting three realistic v1 integrations (a CI submit-and-poll job, a dashboard and an incident script) using only the guide. Its findings were checked against both specs and fixed.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
trunk	🟢 Ready	View Preview	Sep 29, 2026, 4:08 PM

[mintlify]

Docs PR opened: #374

Added a draft Merge Queue API v2 changelog post and updated the changelog pages, to be merged after release.