feat(api): OpenAPI surface, MCP tools, conversation actions & API keys

[melihsunbul]

What

The external API surface: a comprehensive OpenAPI document, MCP tool expansion, conversation action endpoints, comment reactions, moderation, chat tags and API keys.

Concepts

• OpenAPI as a contract — the v1 surface is fully described in openapi.json; a route-coverage test fails the build if a route ships undocumented.
• MCP tools — the same domain operations exposed as tools an AI agent can call (tickets, routing, threads/attachments, and the rest of the new surface).
• Conversation actions — discrete, auditable operations on a conversation (assign, reply, note, priority, read, end, status, tags) rather than free-form mutation.
• API key scopes — keys are scope-gated so an integration only gets the access it needs.

How it works

• OpenAPI — openapi.json regenerated for the full v1 surface; schema modules under domains/api/schemas/ (tickets, roles, teams, segments, settings, suggestions, help-centre, widget-profiles, user-attributes, portal-tabs, chat-tags, conversation-actions, moderation, comments/reactions, apps) registered via openapi.ts/index.ts; openapi-route-coverage.test.ts asserts every route is documented.
• MCP (server/mcp/tools.ts) — tools across all new domains, including manage_routing_rule (create/update/delete/reorder) and thread/attachment tools (getThread, attachToThread, listAttachmentsForThread, removeAttachment, canEditFields); handler tests updated.
• Conversation actions — /api/v1/conversations (assign, reply, note, priority, read, end, status, tags), /comments/{id}/reactions add/remove, /chat-tags CRUD plus attach/detach, and moderation review/actions (domains/moderation/).
• API keys (domains/api-keys/) — scope-gated management.

How to use

• Read the API: the generated openapi.json documents every v1 route and schema; point your client/codegen at it.
• Issue API keys: create scoped keys from the developer/API settings, then call /api/v1/… with the key.
• Drive conversations: use the conversation action endpoints (or the matching MCP tools) to assign, reply, set status/priority and tag.
• Agents: connect via MCP to operate tickets, routing rules and threads programmatically.

Safety

• New endpoints reuse the existing scope/permission gating; the route-coverage test prevents undocumented (and therefore unreviewed) surface from shipping.

Verification

• bun run typecheck, bun run lint; openapi-route-coverage.test.ts, conversation-actions/chat-tags/comment-reactions coverage and MCP handler tests (included).

Depends on 07-widget-profiles.

---

📚 This is a stacked series — please review & merge in order

These 10 PRs are split by concern and ordered by dependency. Each is opened against main, so until the PRs before it have merged, a PR's diff is cumulative (it also contains the earlier batches). As the earlier PRs merge and we rebase the next branch onto main, each diff reduces to just its own batch. Merging all 10 in order reproduces our integrated branch exactly (verified: the cumulative tip of the series is byte-identical to it).

Order (by branch):

1. 01-data-model-foundation — data model, TypeIDs, migrations
2. 02-rbac-authz-teams — RBAC, teams, organisation & auth surfaces
3. 03-events-audit-webhooks — event dispatch, audit log, webhooks, notifications
4. 04-ticketing-crm-core — ticketing / CRM core
5. 05-sla-inboxes-routing — SLA policies, inboxes, business hours, routing
6. 06-github-sync-and-ticket-email — GitHub ticket sync, ticket email, integration platform
7. 07-widget-profiles — scoped widget profiles + ticket submission
8. 08-api-openapi-mcp — OpenAPI surface, MCP tools, conversation actions, API keys
9. 09-content-visibility — changelog/help-centre visibility, segments, portal tabs
10. 10-test-coverage — broad unit/integration test suite + supporting infra

Part of the roadmap: #283

[CLAassistant]

All committers have signed the CLA.