docs(api): improve public API reference documentation

[brendan-kellam]

Summary

• Restructures API reference navigation into grouped sections with icons (Search & Navigation, Repositories, Git, System, Enterprise)
• Adds missing endpoints to the OpenAPI spec: find_definitions, find_references, commits, health, diff, and EE endpoints (/api/ee/user, /api/ee/users, /api/ee/audit)
• Adds descriptions to all documented endpoints
• Adds authentication overview page with API key creation guide and usage example
• Reuses existing Zod schemas (repositoryQuerySchema, listReposQueryParamsSchema, getVersionResponseSchema) in publicApiSchemas.ts instead of duplicating them
• Adds CLAUDE.md guidance on registering new routes in the public API spec

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new authentication reference guide with step-by-step API key setup instructions and usage examples.
  • Enhanced API documentation organization with a new Overview section in the API Reference.
  • Improved clarity of authentication method descriptions in API documentation.
  • Reorganized Enterprise endpoint grouping for better documentation structure.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
sourcebot	🟢 Ready	View Preview	Apr 1, 2026, 6:53 PM

[github-actions]

@brendan-kellam your pull request is missing a changelog!

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 21253ca6-b3cf-42c0-a6a6-5f12d1836a67

📥 Commits

Reviewing files that changed from the base of the PR and between 2509133 and ec51fd6.

📒 Files selected for processing (5)

• CLAUDE.md
• docs/api-reference/sourcebot-public.openapi.json
• docs/docs.json
• docs/docs/api-reference/authentication.mdx
• packages/web/src/openapi/publicApiDocument.ts

---

Walkthrough

This change consolidates Enterprise-specific OpenAPI tags into a unified "Enterprise (EE)" designation, updates security scheme documentation, adds authentication guidance for API consumers, and introduces a workflow guide for API route handler implementation in public API registration.

Changes

Cohort / File(s)	Summary
Documentation and Navigation CLAUDE.md, docs/docs.json, docs/docs/api-reference/authentication.mdx	Added API route handler registration workflow guidance, expanded API Reference navigation with new Overview section, and created authentication documentation page covering API key creation, usage patterns, and curl examples.
OpenAPI Specification docs/api-reference/sourcebot-public.openapi.json, packages/web/src/openapi/publicApiDocument.ts	Consolidated separate "User Management (EE)" and "Audit (EE)" tags into unified "Enterprise (EE)" tag across all EE endpoints. Updated bearer token and API key security scheme descriptions to use generic format documentation. Added x-mint metadata noting Enterprise license requirement on affected endpoints (/api/ee/user, /api/ee/users, /api/ee/audit).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: Improve API docs #1066: Directly modifies the same OpenAPI tag consolidation and security scheme descriptions for Enterprise endpoints.
• feat(web): add GET /api/diff endpoint #1063: Updates security-scheme names and descriptions alongside OpenAPI endpoint taggings in packages/web/src/openapi/publicApiDocument.ts.
• feat(api): document public API authentication #1038: Modifies OpenAPI generation files with related changes to authentication descriptions and OpenAPI metadata structures.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch brendan/improve-public-api-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}