> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Api route catalog

# Web API route catalog

This is the complete route-entry-point inventory for the web app as of 2026-08-30. It is intended as a working catalog for monitoring, security review, contract testing, and incident response.

## Scope and reading guide

* Source of truth for route existence: every `src/app/api/**/route.ts` file. The inventory contains 196 route entry points: 34 non-versioned routes and 162 `/api/v1` routes. Test files are not endpoints.
* Next.js dynamic segments are shown in the same notation as the source: `[id]` and `[...path]`.
* Most user-facing `/api/v1` requests pass through `src/app/api/v1/_utils/bff.ts`, which authenticates the caller, parses the request, resolves workspace context, applies route policy/idempotency/rate-limit behavior, and delegates to the server implementation. Direct routes and internal callbacks are marked below; the per-route file list names the transport entry point and the implementation or direct service files.
* `src/server/app-api/v1/**/route.ts` is server-only domain logic, not a second public URL. Where the app route delegates directly to another app route, that is called out explicitly.
* “Authenticated” means the BFF/app auth resolver accepts a browser session, supported bearer token, or API key for that route. “Host-authenticated” means the connected-agent request signature and exact environment binding are required. “Internal” means the internal service secret is required.
* The generated OpenAPI file is intentionally incomplete for several legacy, streaming, extension, admin, and connected-agent routes; this catalog is broader than `docs/openapi/overlay-web.openapi.json`.

## 1. Authentication, sessions, account, and cross-surface handoff

* `POST /api/account/delete` — Authenticates the current web user, verifies same-origin confirmation, rate-limits the operation, deletes account data through the configured provider, and clears the session. Files: `src/app/api/account/delete/route.ts`; `src/server/account/AccountDeletionService.ts`; `src/server/auth/app-api-auth.ts`; `src/server/auth/session.ts`; `src/server/security/rate-limit.ts`.
* `GET /api/auth/callback` — Completes the configured browser SSO callback after consuming one-time authorization state, upserts the user, and redirects to the requested web or native handoff destination. Files: `src/app/api/auth/callback/route.ts`; `src/server/auth/actions.ts`; `src/server/auth/session.ts`; `src/server/auth/session-transfer-crypto.ts`; `src/server/database/convex.ts`.
* `GET /api/auth/convex-token` — Exchanges the authenticated web session’s access token for a browser-scoped Convex access token. Files: `src/app/api/auth/convex-token/route.ts`; `src/server/auth/browser-convex-token.ts`; `src/server/auth/session.ts`.
* `POST, GET /api/auth/desktop-link` — Creates a short-lived, PKCE-bound desktop/Chrome session-transfer deep link, or consumes that one-time token when the client presents the verifier. Files: `src/app/api/auth/desktop-link/route.ts`; `src/server/auth/session-transfer-crypto.ts`; `src/server/auth/actions.ts`; `src/server/database/convex.ts`; `src/server/shared/internal-api-secret.ts`.
* `POST /api/auth/forgot-password` — Validates and rate-limits a password-reset request, delegating delivery and provider-specific behavior to the auth actions layer. Files: `src/app/api/auth/forgot-password/route.ts`; `src/server/auth/actions.ts`; `src/server/security/rate-limit.ts`.
* `POST /api/auth/native/authorize` — Validates native PKCE state, redirect URI, provider, capability, and rate limits, then returns the server-owned authorization URL. Files: `src/app/api/auth/native/authorize/route.ts`; `src/server/auth/actions.ts`; `src/server/auth/native-auth-validation.ts`; `src/server/security/rate-limit.ts`; `src/server/capabilities.ts`.
* `POST /api/auth/native/exchange` — Validates a native authorization code and PKCE verifier, exchanges them for a native session, and synchronizes the user profile. Files: `src/app/api/auth/native/exchange/route.ts`; `src/server/auth/actions.ts`; `src/server/auth/native-auth-validation.ts`; `src/server/bootstrap.ts`; `src/server/security/rate-limit.ts`.
* `POST /api/auth/native/refresh` — Validates and rate-limits a native refresh-token request, returning refreshed session material when the configured provider supports it. Files: `src/app/api/auth/native/refresh/route.ts`; `src/server/auth/actions.ts`; `src/server/auth/native-refresh-rate-limit.ts`; `src/server/security/rate-limit.ts`.
* `GET /api/auth/native/subscription` — Authenticates a native bearer/session caller and returns normalized entitlement, credit-used, and credit-total fields without caching. Files: `src/app/api/auth/native/subscription/route.ts`; `src/server/auth/app-api-auth.ts`; `src/server/bootstrap.ts`; `src/server/app-data/repositories.ts`; `src/server/security/rate-limit.ts`.
* `GET /api/auth/options` — Returns the configured auth UI/provider options with no-store caching. Files: `src/app/api/auth/options/route.ts`; `src/server/auth/actions.ts`.
* `POST /api/auth/reset-password` — Validates a reset token and new password, with independent IP/token rate limits, then delegates the password update to the auth provider. Files: `src/app/api/auth/reset-password/route.ts`; `src/server/auth/actions.ts`; `src/server/security/rate-limit.ts`.
* `GET /api/auth/session` — Returns the current session/auth diagnostic view with no-store headers and request rate limiting. Files: `src/app/api/auth/session/route.ts`; `src/server/auth/session.ts`; `src/server/auth/auth-debug.ts`; `src/server/config/index.ts`; `src/server/security/rate-limit.ts`.
* `POST /api/auth/sign-in` — Authenticates email/password credentials and returns the provider result, applying IP, email, and combined rate limits. Files: `src/app/api/auth/sign-in/route.ts`; `src/server/auth/actions.ts`; `src/server/security/rate-limit.ts`.
* `POST /api/auth/sign-out` — Clears the current Overlay session cookie. Files: `src/app/api/auth/sign-out/route.ts`; `src/server/auth/session.ts`.
* `POST /api/auth/sign-up` — Creates a password-based account through the configured auth provider with abuse-rate limiting. Files: `src/app/api/auth/sign-up/route.ts`; `src/server/auth/actions.ts`; `src/server/security/rate-limit.ts`.
* `GET /api/auth/sso/[provider]` — Starts the configured SSO provider flow and redirects the browser to the provider authorization endpoint. Files: `src/app/api/auth/sso/[provider]/route.ts`; `src/server/auth/actions.ts`; `src/server/capabilities.ts`.
* `POST /api/auth/sync-profile` — Reads the current session, upserts the application user/profile, and records the signed-in product event for returning users. Files: `src/app/api/auth/sync-profile/route.ts`; `src/server/auth/session.ts`; `src/server/bootstrap.ts`; `src/server/observability/context.ts`; `src/server/observability/posthog-server.ts`.
* `POST /api/auth/verify-email` — Validates an email-verification token and delegates verification to the configured auth provider with rate limiting. Files: `src/app/api/auth/verify-email/route.ts`; `src/server/auth/actions.ts`; `src/server/security/rate-limit.ts`.
* `GET, POST, PATCH, PUT, DELETE /api/better-auth/[...all]` — Catch-all Better Auth transport adapter for the provider’s own authentication endpoints. Files: `src/app/api/better-auth/[...all]/route.ts`; `src/server/auth/better-auth.ts`.

## 2. Billing, subscriptions, releases, and billing webhooks

* `POST /api/checkout` — Creates a personal checkout session after billing capability, session, and rate-limit checks. Files: `src/app/api/checkout/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCheckoutService.ts`; `src/server/auth/session.ts`; `src/server/capabilities.ts`.
* `POST /api/checkout/verify` — Verifies the current user’s checkout result and returns the resulting billing state. Files: `src/app/api/checkout/verify/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCheckoutService.ts`; `src/server/auth/session.ts`; `src/server/capabilities.ts`.
* `GET /api/entitlements` — Returns the authenticated user’s effective billing entitlements, including workspace-aware payer resolution where enabled. Files: `src/app/api/entitlements/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCustomerService.ts`; `src/server/auth/session.ts`.
* `POST /api/portal` — Creates a personal billing portal session after capability, session, origin/rate-limit, and provider checks. Files: `src/app/api/portal/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCustomerService.ts`; `src/server/auth/session.ts`; `src/server/bootstrap.ts`.
* `GET /api/subscription` — Returns the authenticated user’s personal subscription view and rejects attempts to query another user. Files: `src/app/api/subscription/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCustomerService.ts`; `src/server/auth/session.ts`; `src/server/capabilities.ts`.
* `GET, POST /api/subscription/settings` — Reads or updates personal billing settings; the mutation requires explicit confirmation and same-origin protection. Files: `src/app/api/subscription/settings/route.ts`; `src/server/billing/http.ts`; `src/server/auth/app-api-auth.ts`; `src/server/auth/session.ts`; `src/server/bootstrap.ts`; `src/server/security/rate-limit.ts`.
* `POST /api/topups/checkout` — Creates a personal purchased-credit/top-up checkout session for the authenticated user. Files: `src/app/api/topups/checkout/route.ts`; `src/server/billing/http.ts`; `src/server/auth/app-api-auth.ts`; `src/server/auth/session.ts`; `src/server/security/rate-limit.ts`.
* `GET /api/topups/history` — Lists the authenticated user’s purchased-credit/top-up history. Files: `src/app/api/topups/history/route.ts`; `src/server/billing/http.ts`; `src/server/auth/app-api-auth.ts`; `src/server/capabilities.ts`.
* `POST /api/topups/verify` — Verifies a top-up checkout/payment result for the authenticated user. Files: `src/app/api/topups/verify/route.ts`; `src/server/billing/http.ts`; `src/server/auth/app-api-auth.ts`; `src/server/security/rate-limit.ts`.
* `POST /api/webhooks/stripe` — Accepts a raw Stripe webhook only when billing is enabled and configured for PostgreSQL, verifies the Stripe signature, applies idempotent billing events, and records an audit event. Files: `src/app/api/webhooks/stripe/route.ts`; `src/server/billing/StripeWebhookService.ts`; `src/server/billing/stripe-webhook-verifier.ts`; `src/server/billing/BillingRepository.ts`; `src/server/billing/BillingProviderEventRepository.ts`; `src/server/config/index.ts`.
* `GET /api/latest-release` — Returns the latest official desktop release metadata when official downloads are enabled; otherwise it returns the frozen/disabled response. Files: `src/app/api/latest-release/route.ts`; `src/shared/web/latest-release.ts`; `src/server/releases/desktop-download-policy.ts`.
* `GET /api/latest-release/download` — Resolves the latest official desktop download metadata/redirect when official downloads are enabled. Files: `src/app/api/latest-release/download/route.ts`; `src/shared/web/latest-release.ts`; `src/server/releases/desktop-download-policy.ts`.

## 3. Deployment discovery, bootstrap, capability, and transport boundaries

* `POST /api/convex/[type]` — Explicitly rejects direct Convex query, mutation, or action proxying with `410`; callers must use typed application routes. Files: `src/app/api/convex/[type]/route.ts`.
* `GET /api/v1/capabilities` — Publishes deployment/runtime capabilities, app-shell navigation/settings metadata, feature flags, destinations, and an optionally redacted system summary. Files: `src/app/api/v1/capabilities/route.ts`; `src/server/config/index.ts`; `src/server/capabilities.ts`; `src/server/app-data/capabilities.ts`; `src/overlay.config.ts`; `packages/overlay-app-core/src/capabilities.ts`; `packages/overlay-app-core/src/contracts.ts`.
* `GET /api/v1/discovery` — Returns the public protocol/version, deployment identifier, hosted-inference/BYOK capability state, minimum desktop version, and native-auth endpoint locations. Files: `src/app/api/v1/discovery/route.ts`; `src/server/ai/gateway/hosted-provider-kill-switch.ts`; `packages/overlay-api-client/src/index.ts`.
* `GET /api/v1/bootstrap` — Loads the signed-in app registry and state: user, effective entitlements, navigation, settings, feature flags, models, tools/integrations, defaults, and UI settings. Files: `src/app/api/v1/bootstrap/route.ts`; `src/server/app-api/v1/bootstrap/route.ts`; `src/server/bootstrap.ts`; `src/server/config/index.ts`; `src/overlay.config.ts`; `packages/overlay-app-core/src/app-shell.ts`; `packages/overlay-app-core/src/contracts.ts`.
* `GET /api/v1/model-catalog` — Returns the server’s allowed model catalog for the current caller/runtime. Files: `src/app/api/v1/model-catalog/route.ts`; `src/server/app-api/v1/model-catalog/route.ts`; `src/server/ai/model-policy-authority.ts`; `src/shared/ai/gateway/model-data.ts`.
* `GET /api/v1/chat-suggestions` — Returns bounded chat starter suggestions selected for the current app/user context. Files: `src/app/api/v1/chat-suggestions/route.ts`; `src/server/app-api/v1/chat-suggestions/route.ts`.
* `GET /api/v1/mention-search` — Performs bounded indexed search across mentionable conversations, files, notes, automations, skills, MCPs, and related categories. Files: `src/app/api/v1/mention-search/route.ts`; `src/server/app-api/v1/mention-search/route.ts`; `convex/search/mentions.ts`.
* `GET /api/v1/search` — Runs the general authorized workspace/application search contract. Files: `src/app/api/v1/search/route.ts`; `src/server/app-api/v1/search/route.ts`; `src/server/search/WorkspaceSearchService.ts`.
* `POST /api/v1/knowledge/search` — Searches the cross-resource knowledge surface, combining the enabled file, memory, note, project, and indexed-document providers. Files: `src/app/api/v1/knowledge/search/route.ts`; `src/server/app-api/v1/knowledge/search/route.ts`; `src/server/knowledge/KnowledgeSearchService.ts`; `src/server/billing/WorkspaceBillingService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/webhooks` — Lists webhook subscriptions or deliveries, creates a subscription, updates/rotates/redrives it, or deletes it; destination URLs are validated against the public-network/HTTPS policy. Files: `src/app/api/v1/webhooks/route.ts`; `src/server/app-api/v1/webhooks/route.ts`; `src/server/app-data/contracts/automation-webhook-contract.ts`; `src/server/security/ssrf.ts`.
* `GET, PATCH /api/v1/settings` — Reads or updates the authenticated user’s application settings and preferences. Files: `src/app/api/v1/settings/route.ts`; `src/server/app-api/v1/settings/route.ts`; `src/server/app-data/repositories.ts`.
* `POST /api/security/csp-report` — Accepts browser Content-Security-Policy violation reports, applying a dedicated rate limit and security-event logging path. Files: `src/app/api/security/csp-report/route.ts`; `src/server/observability/security-events.ts`; `src/server/security/rate-limit.ts`.

## 4. Administration, authorization, governance, and API keys

* `GET /api/v1/admin/audit` — Lists filtered audit events after checking administrative audit-view authority; denied attempts are themselves audited. Files: `src/app/api/v1/admin/audit/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/server/admin/AdministrativeService.ts`; `src/server/admin/AuditService.ts`.
* `GET, POST, DELETE /api/v1/admin/principals` — Lists administrative principals, grants an administrative role, or revokes a principal with audit metadata and role validation. Files: `src/app/api/v1/admin/principals/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/server/admin/AdministrativeService.ts`; `src/server/admin/AuditService.ts`.
* `GET, POST /api/v1/admin/usage` — Lists administrative usage/budget rows or applies a bounded, reason-required budget adjustment; successful and denied operations are audited. Files: `src/app/api/v1/admin/usage/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/server/admin/AdministrativeService.ts`; `src/server/billing/BillingRepository.ts`; `src/server/admin/AuditService.ts`.
* `GET /api/v1/admin/catalog` — Builds a deduplicated admin catalog of chat/image/video models, internal tools, app-shell connectors, and provider-discovered connectors. Files: `src/app/api/v1/admin/catalog/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/shared/ai/gateway/model-data.ts`; `src/server/integrations/IntegrationService.ts`; `src/overlay.config.ts`; `packages/overlay-tools-core/src/definitions.ts`; `packages/overlay-app-core/src/contracts.ts`.
* `GET /api/v1/admin/knowledge-bases` — Lists knowledge bases visible to an administrator across the configured provider. Files: `src/app/api/v1/admin/knowledge-bases/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/server/bootstrap.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`; `src/server/app-api/v1/knowledge-bases/errors.ts`.
* `GET, POST, DELETE /api/v1/admin/knowledge-bases/defaults` — Lists, assigns, or removes group-level default knowledge bases for the authenticated administrator. Files: `src/app/api/v1/admin/knowledge-bases/defaults/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/server/bootstrap.ts`; `src/server/app-api/v1/knowledge-bases/errors.ts`.
* `GET /api/v1/admin/authorization/capabilities` — Lists the authorization capabilities available to the administrative actor. Files: `src/app/api/v1/admin/authorization/capabilities/route.ts`; `src/app/api/v1/admin/authorization/_utils.ts`; `src/server/authorization/AuthorizationAdministrationService.ts`; `src/server/authorization/authorization-denial-audit.ts`.
* `GET, POST, DELETE /api/v1/admin/authorization/assignments` — Lists role assignments, assigns a role to a user/group, or revokes a role; `roleId` changes the GET view to role-centric listing. Files: `src/app/api/v1/admin/authorization/assignments/route.ts`; `src/app/api/v1/admin/authorization/_utils.ts`; `src/server/authorization/AuthorizationAdministrationService.ts`.
* `GET, POST, DELETE /api/v1/admin/authorization/grants` — Lists, upserts, or removes resource grants for principals and governed resources. Files: `src/app/api/v1/admin/authorization/grants/route.ts`; `src/app/api/v1/admin/authorization/_utils.ts`; `src/server/authorization/AuthorizationAdministrationService.ts`; `packages/overlay-authz-contracts/src/types.ts`.
* `GET, POST, PATCH, DELETE /api/v1/admin/authorization/groups` — Lists, creates, updates, or archives authorization groups. Files: `src/app/api/v1/admin/authorization/groups/route.ts`; `src/app/api/v1/admin/authorization/_utils.ts`; `src/server/authorization/AuthorizationAdministrationService.ts`.
* `GET, POST, DELETE /api/v1/admin/authorization/memberships` — Lists, adds, or removes group memberships. Files: `src/app/api/v1/admin/authorization/memberships/route.ts`; `src/app/api/v1/admin/authorization/_utils.ts`; `src/server/authorization/AuthorizationAdministrationService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/admin/authorization/roles` — Lists, creates, updates, or archives custom authorization roles and their capability sets. Files: `src/app/api/v1/admin/authorization/roles/route.ts`; `src/app/api/v1/admin/authorization/_utils.ts`; `src/server/authorization/AuthorizationAdministrationService.ts`; `packages/overlay-authz-contracts/src/types.ts`.
* `GET, POST, PATCH /api/v1/admin/governance/policies` — Lists policies, creates a policy version, or approves/rejects a policy version for a governed resource. Files: `src/app/api/v1/admin/governance/policies/route.ts`; `src/app/api/v1/admin/governance/_utils.ts`; `src/server/governance/GovernanceService.ts`; `src/server/admin/AuditService.ts`.
* `GET, POST, PATCH /api/v1/admin/governance/reviews` — Lists access reviews, creates a review, or completes a review with reviewer notes. Files: `src/app/api/v1/admin/governance/reviews/route.ts`; `src/app/api/v1/admin/governance/_utils.ts`; `src/server/governance/GovernanceService.ts`; `src/server/admin/AuditService.ts`.
* `GET /api/v1/admin/governance/export` — Exports compliance evidence as JSON or CSV, including policies, access reviews, and audit events. Files: `src/app/api/v1/admin/governance/export/route.ts`; `src/app/api/v1/admin/governance/_utils.ts`; `src/server/governance/GovernanceService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/api-keys` — Lists owned API keys, creates a key, rotates a key, or revokes a key; admin-scoped creation is separately authorized and lifecycle/audit events are published. Files: `src/app/api/v1/api-keys/route.ts`; `src/app/api/v1/_utils/bff.ts`; `src/server/auth/api-keys/ApiKeyService.ts`; `src/server/auth/api-keys/crypto.ts`; `src/server/admin/AdministrativeService.ts`; `src/server/admin/AuditService.ts`.

## 5. Connected agents, environments, hosts, and remote artifacts

* `GET /api/v1/agent-environments` — Lists the authenticated workspace’s connected agent environments; an environment stored as online is presented as offline after 45 seconds without a heartbeat. Files: `src/app/api/v1/agent-environments/route.ts`; `src/server/app-api/v1/agent-environments/route.ts`; `src/server/app-api/v1/agent-environments/shared.ts`; `src/server/agents/ConnectedAgentControlPlaneService.ts`.
* `POST /api/v1/agent-environments/enrollment-sessions` — Creates a short-lived browser enrollment session and returns the one-time host enrollment command pinned to Node 24 and the exact Agent Host package; the code is not persisted in raw form. Files: `src/app/api/v1/agent-environments/enrollment-sessions/route.ts`; `src/server/app-api/v1/agent-environments/enrollment-sessions/route.ts`; `src/server/agents/agent-enrollment-command.ts`; `src/server/app-api/v1/agent-environments/shared.ts`.
* `POST /api/v1/agent-environments/enroll` — Redeems a one-time enrollment code to establish a pending connected environment. Files: `src/app/api/v1/agent-environments/enroll/route.ts`; `src/server/app-api/v1/agent-environments/enroll/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/managed` — Provisions an Overlay-managed environment through the sandbox runtime, using entitlement/policy checks and the same normal approval flow as a host enrollment. Files: `src/app/api/v1/agent-environments/managed/route.ts`; `src/server/app-api/v1/agent-environments/managed/route.ts`; `src/server/agents/ManagedAgentSandboxService.ts`; `src/server/agents/ConnectedAgentPolicy.ts`; `packages/overlay-sandbox-runtime/src/index.ts`; `packages/overlay-sandbox-runtime/src/contracts.ts`.
* `POST /api/v1/agent-environments/[environmentId]/approve` — Approves a pending environment and assigns the requested filesystem grant. Files: `src/app/api/v1/agent-environments/[environmentId]/approve/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/approve/route.ts`; `src/server/app-api/v1/agent-environments/shared.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/revoke` — Revokes an approved/pending environment and invalidates its future host access. Files: `src/app/api/v1/agent-environments/[environmentId]/revoke/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/revoke/route.ts`; `src/server/app-api/v1/agent-environments/shared.ts`.
* `PATCH /api/v1/agent-environments/[environmentId]/roots` — Updates the browser-authorized filesystem root/grant for an environment. Files: `src/app/api/v1/agent-environments/[environmentId]/roots/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/roots/route.ts`; `src/server/app-api/v1/agent-environments/shared.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `PUT /api/v1/agent-environments/[environmentId]/capabilities` — Accepts a host capability refresh after host authentication and stores the normalized capability set. Files: `src/app/api/v1/agent-environments/[environmentId]/capabilities/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/capabilities/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/credentials` — Issues the initial host credential after validating the enrollment proof and exact environment binding. Files: `src/app/api/v1/agent-environments/[environmentId]/credentials/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/credentials/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/credentials/refresh` — Refreshes a host credential after validating the signed request, nonce, expiry, method, body, and environment binding. Files: `src/app/api/v1/agent-environments/[environmentId]/credentials/refresh/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/credentials/refresh/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`.
* `GET /api/v1/agent-environments/[environmentId]/commands` — Host-polls bounded pending commands for its exact environment and protocol version. Files: `src/app/api/v1/agent-environments/[environmentId]/commands/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/commands/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/commands/[commandId]/ack` — Authenticates a host command acknowledgement, verifies the route/body command ID match, and records ordered acknowledgement. Files: `src/app/api/v1/agent-environments/[environmentId]/commands/[commandId]/ack/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/commands/[commandId]/ack/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/heartbeat` — Refreshes host liveness for the exact environment after host request authentication. Files: `src/app/api/v1/agent-environments/[environmentId]/heartbeat/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/heartbeat/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`.
* `POST /api/v1/agent-environments/[environmentId]/events` — Applies a signed, ordered host event batch and returns the acknowledgement cursor. Files: `src/app/api/v1/agent-environments/[environmentId]/events/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/events/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/artifacts` — Creates a host-scoped artifact upload intent after validating type/size and the signed environment request. Files: `src/app/api/v1/agent-environments/[environmentId]/artifacts/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/artifacts/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/[environmentId]/artifacts/[artifactId]/complete` — Completes an artifact upload after checking the route/reference match, host signature, checksum/type/size, and retention/tenancy rules. Files: `src/app/api/v1/agent-environments/[environmentId]/artifacts/[artifactId]/complete/route.ts`; `src/server/app-api/v1/agent-environments/[environmentId]/artifacts/[artifactId]/complete/route.ts`; `src/server/app-api/v1/agent-environments/host-security.ts`; `packages/overlay-agent-bridge-protocol/src/index.ts`.
* `POST /api/v1/agent-environments/artifacts/cleanup` — Internal scheduler endpoint that deletes expired/unprojected artifact objects in a bounded batch. Files: `src/app/api/v1/agent-environments/artifacts/cleanup/route.ts`; `src/server/app-api/v1/agent-environments/artifacts/cleanup/route.ts`; `src/server/shared/internal-api-secret.ts`; `src/server/storage/object-store.ts`.
* `POST /api/v1/agent-environments/operations/reconcile` — Internal scheduler endpoint that sweeps remote-run supervision and reconciles sandbox settlement records. Files: `src/app/api/v1/agent-environments/operations/reconcile/route.ts`; `src/server/app-api/v1/agent-environments/operations/reconcile/route.ts`; `src/server/shared/internal-api-secret.ts`; `src/server/agents/ConnectedAgentControlPlaneService.ts`.
* `GET, PUT, DELETE /api/v1/agent-bindings` — Lists, upserts, or disables the workspace-owned mapping from an Overlay agent to an approved environment, adapter, and working directory. Files: `src/app/api/v1/agent-bindings/route.ts`; `src/server/app-api/v1/agent-bindings/route.ts`; `src/server/app-api/v1/agent-environments/shared.ts`.
* `GET, POST /api/v1/agents` — Lists workspace agents or creates a workspace agent identity/configuration. `POST` accepts an optional `visibility` (`creator` for Only me, `workspace` for Everyone; defaults to `workspace`). `GET` only returns agents visible to the caller: creator-only agents are limited to their creator. Files: `src/app/api/v1/agents/route.ts`; `src/server/app-api/v1/agents/route.ts`; `src/server/app-api/v1/agents/shared.ts`; `src/server/agents/WorkspaceAgentService.ts`.
* `GET, PATCH, DELETE /api/v1/agents/[agentId]` — Reads, updates, or archives one workspace agent. `PATCH` accepts an optional `visibility` flip. Reads/updates of a creator-only agent by anyone but its creator return 404 (existence is not disclosed); updates of a visible agent by a non-creator non-manager return 403; workspace managers may archive (but not edit) creator-only agents. Files: `src/app/api/v1/agents/[agentId]/route.ts`; `src/server/app-api/v1/agents/[agentId]/route.ts`; `src/server/app-api/v1/agents/shared.ts`.

## 6. Automations and durable workflow execution

* `GET, POST, PATCH, DELETE /api/v1/automations` — Lists, creates, updates, or deletes the authenticated user’s automation definitions, including graph/schedule metadata. Files: `src/app/api/v1/automations/route.ts`; `src/server/app-api/v1/automations/route.ts`; `src/server/automations/http.ts`; `src/server/automations/AutomationService.ts`; `src/server/automations/AutomationRepository.ts`.
* `POST /api/v1/automations/test` — Validates/tests an automation definition without treating the request as a durable scheduled run. Files: `src/app/api/v1/automations/test/route.ts`; `src/server/app-api/v1/automations/test/route.ts`; `src/server/automations/http.ts`; `src/server/web/app-url.ts`.
* `POST /api/v1/automations/run` — Runs an automation through the service-authenticated execution path used by durable workflow callbacks/internal callers. Files: `src/app/api/v1/automations/run/route.ts`; `src/server/app-api/v1/automations/run/route.ts`; `src/server/auth/service-auth.ts`; `src/server/auth/service-auth-replay.ts`; `src/server/automations/http.ts`.
* `POST, PATCH /api/v1/automations/execute` — Internal execution callback that resolves an automation/conversation target, marks a run started, and finalizes it as completed or failed. Files: `src/app/api/v1/automations/execute/route.ts`; `src/server/app-api/v1/automations/execute/route.ts`; `src/server/auth/service-auth.ts`; `src/server/auth/service-auth-replay.ts`; `src/server/automations/http.ts`.
* `POST /api/v1/automations/[id]/run` — Starts a durable workflow run for a specific automation after rechecking user/workspace access and builds condition-approval state when needed. Files: `src/app/api/v1/automations/[id]/run/route.ts`; `src/server/app-api/v1/automations/[id]/run/route.ts`; `workflows/automation-schedule.ts`; `src/server/automations/http.ts`.
* `POST /api/v1/automations/[id]/approve` — Consumes an automation approval token and resumes/records approval for the selected automation execution. Files: `src/app/api/v1/automations/[id]/approve/route.ts`; `src/server/app-api/v1/automations/[id]/approve/route.ts`; `src/server/automations/http.ts`; `workflows/automation-schedule.ts`.
* `POST /api/v1/automations/[id]/start-scheduler` — Starts or reactivates scheduling for a specific automation after ownership/authorization checks. Files: `src/app/api/v1/automations/[id]/start-scheduler/route.ts`; `src/server/app-api/v1/automations/[id]/start-scheduler/route.ts`; `src/server/automations/http.ts`.
* `POST /api/v1/automations/[id]/cancel-scheduler` — Cancels the workflow scheduler run associated with an automation. Files: `src/app/api/v1/automations/[id]/cancel-scheduler/route.ts`; `src/server/app-api/v1/automations/[id]/cancel-scheduler/route.ts`; `src/server/automations/http.ts`; `workflows/automation-schedule.ts`.
* `GET /api/v1/automations/[id]/events` — Streams durable workflow step events over SSE, with optional cursor/resume support for non-Convex/fallback clients. Files: `src/app/api/v1/automations/[id]/events/route.ts`; `src/server/app-api/v1/automations/[runId]/events/route.ts`; `workflow/runtime` and `workflow/api`.
* `GET /api/v1/automations/[id]/stream` — Streams the automation run’s live output/events over the fallback SSE route. Files: `src/app/api/v1/automations/[id]/stream/route.ts`; `src/server/app-api/v1/automations/[runId]/stream/route.ts`; `workflow/runtime` and `workflow/api`.

## 7. Conversations, collaboration rooms, and AgentRun lifecycle

* `GET, POST, PATCH, DELETE /api/v1/conversations` — Lists authorized conversations or a project/view slice, creates a conversation, updates metadata, or deletes/archives a conversation; GET supports bounded message/tail and cursor parameters. Files: `src/app/api/v1/conversations/route.ts`; `src/server/app-api/v1/conversations/route.ts`; `src/server/app-data/repositories.ts`; `src/server/app-api/pagination-core.ts`.
* `POST, DELETE /api/v1/conversations/message` — Appends a user/collaboration message and returns its persisted ID, or removes the targeted message according to the route’s deletion contract. If an invoked workspace agent cannot start, POST preserves a visible failed assistant row with safe retry guidance instead of silently swallowing the start failure. Files: `src/app/api/v1/conversations/message/route.ts`; `src/server/app-api/v1/conversations/message/route.ts`; `src/server/app-api/v1/conversations/message/agent-start-failure.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`; `src/server/conversations/ActConversationRepository.ts`.
* `POST /api/v1/conversations/act` — Runs a Chat or Work-mode model turn, streams UI message/tool/approval events over SSE, and persists the terminal assistant snapshot through the AgentRun lifecycle. Files: `src/app/api/v1/conversations/act/route.ts`; `src/server/app-api/v1/conversations/act/route.ts`; `src/server/app-api/v1/conversations/act/route-helpers.ts`; `src/server/app-api/v1/conversations/act/tooling.ts`; `src/server/conversations/ActContextService.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/conversations/act/extension-plan` — Computes the extension/tool plan for an Act request after checking model, capability, mention, and resource authorization. Files: `src/app/api/v1/conversations/act/extension-plan/route.ts`; `src/server/app-api/v1/conversations/act/extension-plan/route.ts`; `src/server/tools/tools/exposure-policy.ts`; `src/server/authorization/resource-route-authorization.ts`.
* `GET /api/v1/conversations/run` — Returns the active non-terminal AgentRun for a conversation, or the most recent terminal run when no slot is active. Files: `src/app/api/v1/conversations/run/route.ts`; `src/server/app-api/v1/conversations/run/route.ts`; `src/server/conversations/AgentRunService.ts`; `src/server/conversations/PostgresActConversationRepository.ts`.
* `POST /api/v1/conversations/agent-greeting` — Posts the new-agent greeting as the agent itself (visibility-enforced, idempotent per conversation+agent). Files: `src/app/api/v1/conversations/agent-greeting/route.ts`; `src/server/app-api/v1/conversations/agent-greeting/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `POST /api/v1/conversations/stop` — Atomically cancels active AgentRuns, projects interruption into assistant messages, and best-effort aborts local tool/workflow execution. Files: `src/app/api/v1/conversations/stop/route.ts`; `src/server/app-api/v1/conversations/stop/route.ts`; `src/server/conversations/AgentRunService.ts`; `src/server/conversations/tool-loop-run-registry.ts`; `workflows/personal-chat-work.ts`.
* `POST /api/v1/conversations/run/approval` — Accepts or denies the current Work-mode approval hook after validating conversation, AgentRun, and hook-token freshness. Files: `src/app/api/v1/conversations/run/approval/route.ts`; `src/server/app-api/v1/conversations/run/approval/route.ts`; `src/server/conversations/AgentRunService.ts`; `src/server/conversations/personal-chat-work-lifecycle.ts`.
* `GET /api/v1/conversations/run/metrics` — Returns bounded runner observations for latency, cost, workflow, disconnect/recovery, tools, cancellation, and stale-run denominators. Files: `src/app/api/v1/conversations/run/metrics/route.ts`; `src/server/app-api/v1/conversations/run/metrics/route.ts`; `src/server/conversations/agent-run-metrics.ts`.
* `POST /api/v1/conversations/run/metrics-event` — Records a browser `disconnected` or `reconnected` observation for an exact AgentRun. Files: `src/app/api/v1/conversations/run/metrics-event/route.ts`; `src/server/app-api/v1/conversations/run/metrics-event/route.ts`; `src/server/conversations/agent-run-metrics.ts`.
* `POST /api/v1/conversations/run/remote` — Controls a connected-agent remote run using the narrow Cancel, Retry, Resume, or Start-fresh command set. Files: `src/app/api/v1/conversations/run/remote/route.ts`; `src/server/app-api/v1/conversations/run/remote/route.ts`; `src/server/agents/ConnectedAgentControlPlaneService.ts`.
* `POST /api/v1/conversations/run/remote/request` — Resolves a pending remote permission or structured elicitation after rechecking the human’s current workspace/room authority. Files: `src/app/api/v1/conversations/run/remote/request/route.ts`; `src/server/app-api/v1/conversations/run/remote/request/route.ts`; `src/server/agents/ConnectedAgentControlPlaneService.ts`.
* `GET /api/v1/conversations/run/remote/artifacts/[artifactId]` — Authorizes the current participant and redirects to a short-lived object-store URL for a validated remote-run artifact. Files: `src/app/api/v1/conversations/run/remote/artifacts/[artifactId]/route.ts`; `src/server/app-api/v1/conversations/run/remote/artifacts/[artifactId]/route.ts`; `src/server/storage/object-store.ts`.
* `GET, POST /api/v1/conversations/channels` — Lists accessible channels or creates a channel in the explicitly selected workspace; browser creation surfaces send `x-overlay-workspace-id` rather than relying on stored active-workspace fallback. Files: `src/app/api/v1/conversations/channels/route.ts`; `src/server/app-api/v1/conversations/channels/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`; `src/server/workspaces/WorkspaceService.ts`; `packages/overlay-api-client/src/chat/conversations-client.ts`.
* `POST /api/v1/conversations/direct-messages` — Creates or opens a direct-message conversation between authorized principals in the explicitly selected workspace; browser creation surfaces send `x-overlay-workspace-id` rather than relying on stored active-workspace fallback. Requested agent principals must resolve to agents visible to the caller — a DM with a creator-only agent by anyone but its creator returns 404 without disclosing whether the agent exists. Files: `src/app/api/v1/conversations/direct-messages/route.ts`; `src/server/app-api/v1/conversations/direct-messages/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`; `packages/overlay-api-client/src/chat/conversations-client.ts`.
* `GET /api/v1/conversations/events` — Streams provider-backed conversation events for Postgres collaboration clients; Convex browsers use native subscriptions instead. Files: `src/app/api/v1/conversations/events/route.ts`; `src/server/app-api/v1/conversations/events/route.ts`; `src/server/conversations/PostgresConversationCollaborationRepository.ts`.
* `GET /api/v1/conversations/search` — Searches authorized conversation titles/messages with bounded query parameters. Files: `src/app/api/v1/conversations/search/route.ts`; `src/server/app-api/v1/conversations/search/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, PATCH /api/v1/conversations/notification-preferences` — Reads or updates the caller’s conversation notification preferences. Files: `src/app/api/v1/conversations/notification-preferences/route.ts`; `src/server/app-api/v1/conversations/notification-preferences/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, PATCH /api/v1/conversations/notifications` — Lists unread notifications or marks notifications read by IDs or conversation ID. Files: `src/app/api/v1/conversations/notifications/route.ts`; `src/server/app-api/v1/conversations/notifications/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, PATCH /api/v1/conversations/saved-messages` — Lists saved messages or creates/updates/removes a saved-message record according to the request body. Files: `src/app/api/v1/conversations/saved-messages/route.ts`; `src/server/app-api/v1/conversations/saved-messages/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `PATCH /api/v1/conversations/share` — Updates conversation sharing state/metadata for an authorized conversation. Files: `src/app/api/v1/conversations/share/route.ts`; `src/server/app-api/v1/conversations/share/route.ts`; `src/server/authorization/resource-route-authorization.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `PATCH, DELETE /api/v1/conversations/[conversationId]/messages/[messageId]` — Edits a message while preserving edit history, or deletes/removes a message after conversation authorization. Files: `src/app/api/v1/conversations/[conversationId]/messages/[messageId]/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/messages/[messageId]/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, POST, DELETE /api/v1/conversations/[conversationId]/participants` — Lists, adds, or removes room participants. Files: `src/app/api/v1/conversations/[conversationId]/participants/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/participants/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`; `src/server/authorization/AuthorizationService.ts`.
* `GET, PATCH /api/v1/conversations/[conversationId]/pins` — Lists pinned messages or changes the caller’s pin state for a conversation message. Files: `src/app/api/v1/conversations/[conversationId]/pins/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/pins/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, PATCH /api/v1/conversations/[conversationId]/presence` — Reads room presence/typing state or updates the caller’s presence heartbeat/state. Files: `src/app/api/v1/conversations/[conversationId]/presence/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/presence/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, PATCH /api/v1/conversations/[conversationId]/reactions` — Lists reactions or adds/removes the caller’s reaction on a message. Files: `src/app/api/v1/conversations/[conversationId]/reactions/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/reactions/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `POST /api/v1/conversations/[conversationId]/reports` — Records a user report against a conversation/message after verifying the caller can access the conversation. Files: `src/app/api/v1/conversations/[conversationId]/reports/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/reports/route.ts`; `src/server/admin/AuditService.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `PATCH /api/v1/conversations/[conversationId]/state` — Updates collaboration conversation state/metadata such as archive or room-level state. Files: `src/app/api/v1/conversations/[conversationId]/state/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/state/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET, PATCH /api/v1/conversations/[conversationId]/threads/[threadRootMessageId]/follow` — Reads thread-follow state and follows/unfollows a thread for the current workspace principal. Files: `src/app/api/v1/conversations/[conversationId]/threads/[threadRootMessageId]/follow/route.ts`; `src/server/app-api/v1/conversations/[conversationId]/threads/[threadRootMessageId]/follow/route.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.

## 8. Files, uploads, outputs, and object storage

* `GET, POST, PATCH, DELETE /api/v1/files` — Lists/gets owner-authorized file metadata, creates a file record, updates metadata, or deletes a file and its associated object/index state. GET supports bounded page/cursor parameters. Files: `src/app/api/v1/files/route.ts`; `src/server/app-api/v1/files/route.ts`; `src/server/files/http.ts`; `src/server/files/FileService.ts`; `src/server/storage/object-store.ts`.
* `POST /api/v1/files/upload-url` — Creates the legacy server-mediated upload URL for an authorized file upload. Files: `src/app/api/v1/files/upload-url/route.ts`; `src/server/app-api/v1/files/upload-url/route.ts`; `src/server/storage/object-store.ts`.
* `GET /api/v1/files/presign` — Creates a short-lived direct-upload/presign response for the durable ingestion flow. Files: `src/app/api/v1/files/presign/route.ts`; `src/server/app-api/v1/files/presign/route.ts`; `src/server/storage/object-store.ts`; `src/server/storage/storage-keys.ts`.
* `POST /api/v1/files/ingest-document` — Accepts the backward-compatible synchronous multipart document upload and runs extraction/indexing in the request path. Files: `src/app/api/v1/files/ingest-document/route.ts`; `src/server/app-api/v1/files/ingest-document/route.ts`; `src/server/files/FileService.ts`; `src/server/knowledge/KnowledgeIndexService.ts`.
* `POST, GET /api/v1/files/ingest-jobs` — Creates a durable document-ingestion job after a direct upload, or returns the current status for a requested job. Files: `src/app/api/v1/files/ingest-jobs/route.ts`; `src/server/app-api/v1/files/ingest-jobs/route.ts`; `src/server/files/FileService.ts`; `convex/files/ingestion/jobs.ts`.
* `POST /api/v1/files/ingest-jobs/process` — Internal worker callback that downloads/validates the uploaded object, extracts content, creates file records, and advances the ingestion job state. Files: `src/app/api/v1/files/ingest-jobs/process/route.ts`; `src/server/app-api/v1/files/ingest-jobs/process/route.ts`; `src/server/shared/internal-api-secret.ts`; `src/server/files/FileService.ts`; `src/server/storage/object-store.ts`.
* `POST /api/v1/files/search-text` — Searches extracted text in owner-authorized files with bounded request/runtime limits. Files: `src/app/api/v1/files/search-text/route.ts`; `src/server/app-api/v1/files/search-text/route.ts`; `src/server/files/FileService.ts`; `src/server/knowledge/KnowledgeSearchService.ts`.
* `GET /api/v1/files/[fileId]/content` — Verifies file ownership/resource authorization and redirects or streams a short-lived object-store download. Files: `src/app/api/v1/files/[fileId]/content/route.ts`; `src/server/app-api/v1/files/[fileId]/content/route.ts`; `src/server/storage/object-store.ts`; `src/server/storage/storage-keys.ts`.
* `PATCH /api/v1/files/share` — Changes a file’s share/public-token state after owner/resource authorization. Files: `src/app/api/v1/files/share/route.ts`; `src/server/app-api/v1/files/share/route.ts`; `src/server/storage/storage-keys.ts`; `src/server/authorization/resource-route-authorization.ts`.
* `GET /api/share/file/[token]` — Resolves a public file/output share token through a server-secret Convex query, verifies the R2 key belongs to the recorded owner, and redirects to a short-lived download URL. Files: `src/app/api/share/file/[token]/route.ts`; `src/server/database/convex.ts`; `src/server/shared/internal-api-secret.ts`; `src/server/storage/object-store.ts`; `src/server/storage/storage-keys.ts`.
* `GET, DELETE /api/v1/outputs` — Lists the caller’s generated outputs or deletes an output record/object after authorization. Files: `src/app/api/v1/outputs/route.ts`; `src/server/app-api/v1/outputs/route.ts`; `src/server/storage/object-store.ts`.
* `GET /api/v1/outputs/[outputId]/content` — Authorizes a generated output and redirects to its short-lived object-store content URL. Files: `src/app/api/v1/outputs/[outputId]/content/route.ts`; `src/server/app-api/v1/outputs/[outputId]/content/route.ts`; `src/server/storage/object-store.ts`; `src/server/storage/storage-keys.ts`.

## 9. Knowledge bases, memories, notes, and projects

* `GET, POST, PATCH, DELETE /api/v1/knowledge-bases` — Lists authorized knowledge bases, creates one, updates metadata, or deletes one; results merge owned and explicitly granted resources. Files: `src/app/api/v1/knowledge-bases/route.ts`; `src/server/app-api/v1/knowledge-bases/route.ts`; `src/server/app-api/v1/knowledge-bases/errors.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `GET, POST /api/v1/knowledge-bases/personal` — Lists or creates the caller’s personal knowledge base. Files: `src/app/api/v1/knowledge-bases/personal/route.ts`; `src/server/app-api/v1/knowledge-bases/personal/route.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`.
* `GET /api/v1/knowledge-bases/share-directory` — Returns the authorized directory of knowledge bases available for sharing/discovery. Files: `src/app/api/v1/knowledge-bases/share-directory/route.ts`; `src/server/bootstrap.ts`; `src/server/app-api/v1/knowledge-bases/errors.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`.
* `GET /api/v1/knowledge-bases/[knowledgeBaseId]/conversations` — Lists conversations associated with an authorized knowledge base. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/conversations/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/conversations/route.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`; `src/server/conversations/ConversationCollaborationRepository.ts`.
* `GET /api/v1/knowledge-bases/[knowledgeBaseId]/diagnostics` — Returns operational/indexing diagnostics for an authorized knowledge base. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/diagnostics/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/diagnostics/route.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`.
* `GET, POST, DELETE /api/v1/knowledge-bases/[knowledgeBaseId]/grants` — Lists, creates, or removes knowledge-base resource grants. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/grants/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/grants/route.ts`; `src/server/authorization/AuthorizationService.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`.
* `GET, POST /api/v1/knowledge-bases/[knowledgeBaseId]/reindex` — Reads reindex/status information or starts a reindex operation for an authorized knowledge base. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/reindex/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/reindex/route.ts`; `src/server/knowledge-bases/KnowledgeSourceIngestionService.ts`; `src/server/knowledge/KnowledgeIndexService.ts`.
* `POST /api/v1/knowledge-bases/[knowledgeBaseId]/search` — Runs retrieval inside one authorized knowledge base and applies the billable-feature/resource scope. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/search/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/search/route.ts`; `src/server/knowledge-bases/KnowledgeBaseRetrievalService.ts`; `src/server/billing/WorkspaceBillingService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/knowledge-bases/[knowledgeBaseId]/sources` — Lists, creates, updates, or removes sources within an authorized knowledge base. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/sources/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/sources/route.ts`; `src/server/knowledge-bases/KnowledgeSourceIngestionService.ts`.
* `POST /api/v1/knowledge-bases/[knowledgeBaseId]/sources/upload` — Creates a text source from an owner-authorized uploaded file and queues/records ingestion. Files: `src/app/api/v1/knowledge-bases/[knowledgeBaseId]/sources/upload/route.ts`; `src/server/app-api/v1/knowledge-bases/[knowledgeBaseId]/sources/upload/route.ts`; `src/server/files/FileService.ts`; `src/server/knowledge-bases/KnowledgeSourceIngestionService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/memory` — Lists workspace-scoped memories, creates a memory attributed to the current user, updates creator-owned memory, or deletes creator-owned memory. Files: `src/app/api/v1/memory/route.ts`; `src/server/app-api/v1/memory/route.ts`; `src/server/memory/MemoryService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/notes` — Lists, creates, updates, or deletes owner/workspace-authorized notes. Files: `src/app/api/v1/notes/route.ts`; `src/server/app-api/v1/notes/route.ts`; `src/server/notes/NoteService.ts`.
* `GET, POST, PATCH, DELETE /api/v1/skills` — Lists, creates, updates, or deletes user/workspace skills, including the directory metadata and on-demand instruction content used by agents. Files: `src/app/api/v1/skills/route.ts`; `src/server/app-api/v1/skills/route.ts`; `convex/integrations/skills.ts`; `src/server/app-data/repositories.ts`.
* `GET, POST, PATCH, DELETE /api/v1/projects` — Lists authorized projects (accepts `archived` query flag; defaults to active projects), creates a project, updates project metadata/instructions/tree relationships/archive state (`archived` boolean), or deletes a project tree. Files: `src/app/api/v1/projects/route.ts`; `src/server/app-api/v1/projects/route.ts`; `src/server/projects/ProjectService.ts`; `src/server/app-api/validated-input.ts`.
* `GET, POST /api/v1/projects/duplicate` — Reads duplicate capability/preview data or duplicates an authorized project tree. Files: `src/app/api/v1/projects/duplicate/route.ts`; `src/server/app-api/v1/projects/duplicate/route.ts`; `src/server/projects/ProjectService.ts`.
* `GET /api/v1/projects/export` — Exports an authorized project and its associated file/knowledge metadata in the requested representation. Files: `src/app/api/v1/projects/export/route.ts`; `src/server/app-api/v1/projects/export/route.ts`; `src/server/projects/ProjectService.ts`; `src/server/storage/object-store.ts`.
* `GET, POST, DELETE /api/v1/projects/grants` — Lists, creates, or removes project resource grants. Files: `src/app/api/v1/projects/grants/route.ts`; `src/server/app-api/v1/projects/grants/route.ts`; `src/server/authorization/AuthorizationService.ts`; `src/server/projects/ProjectSharingService.ts`.
* `GET, POST, DELETE /api/v1/projects/knowledge-bases` — Lists, links, or unlinks knowledge bases associated with an authorized project. Files: `src/app/api/v1/projects/knowledge-bases/route.ts`; `src/server/app-api/v1/projects/knowledge-bases/route.ts`; `src/server/projects/ProjectService.ts`; `src/server/knowledge-bases/KnowledgeBaseService.ts`.
* `POST /api/v1/projects/knowledge-transfer` — Transfers/copies authorized knowledge between the project and selected knowledge-base resources. Files: `src/app/api/v1/projects/knowledge-transfer/route.ts`; `src/server/app-api/v1/projects/knowledge-transfer/route.ts`; `src/server/projects/ProjectKnowledgeTransferService.ts`; `src/server/knowledge-bases/KnowledgeSourceIngestionService.ts`.
* `GET /api/v1/projects/share-directory` — Returns an authorized directory of projects available to the caller for sharing/discovery. Files: `src/app/api/v1/projects/share-directory/route.ts`; `src/server/app-api/v1/projects/share-directory/route.ts`; `src/server/projects/ProjectSharingService.ts`; `src/server/authorization/AuthorizationService.ts`.

## 10. Sharing and workspace collaboration

* `GET, POST, DELETE /api/v1/shares` — Lists shares, creates a share, or removes a share for an authorized resource. Files: `src/app/api/v1/shares/route.ts`; `src/server/app-api/v1/shares/route.ts`; `src/server/authorization/AuthorizationService.ts`; `src/server/projects/ProjectSharingService.ts`.
* `GET /api/v1/shares/shared-with-me` — Lists resources shared with the current user/principal. Files: `src/app/api/v1/shares/shared-with-me/route.ts`; `src/server/app-api/v1/shares/shared-with-me/route.ts`; `src/server/authorization/AuthorizationService.ts`; `src/server/projects/ProjectSharingService.ts`.
* `GET /api/v1/shares/impact` — Computes the authorization/share impact of a proposed sharing change. Files: `src/app/api/v1/shares/impact/route.ts`; `src/server/app-api/v1/shares/impact/route.ts`; `src/server/authorization/resource-route-authorization.ts`; `src/server/projects/ProjectSharingService.ts`.
* `GET, POST /api/v1/workspaces` — Lists the caller’s personal/organization workspace access and creates an organization workspace, setting it active after creation. Browser-session creation seeds the owner principal from the authenticated profile name and email instead of the provider user ID. Files: `src/app/api/v1/workspaces/route.ts`; `src/server/app-api/v1/workspaces/route.ts`; `src/server/app-api/v1/workspaces/presentation.ts`; `src/server/app-api/v1/workspaces/inputs.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `POST /api/v1/workspaces/active` — Sets the caller’s active workspace after verifying workspace membership/access. Files: `src/app/api/v1/workspaces/active/route.ts`; `src/server/app-api/v1/workspaces/active/route.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `POST /api/v1/workspace-invitations/[invitationId]/accept` — Accepts an invitation identified by token/ID and establishes or activates the caller’s membership. Files: `src/app/api/v1/workspace-invitations/[invitationId]/accept/route.ts`; `src/server/app-api/v1/workspace-invitations/[invitationId]/accept/route.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `GET, POST /api/v1/workspaces/[workspaceId]/invitations` — Lists invitations for a workspace or creates/sends an invitation after manager authorization. Files: `src/app/api/v1/workspaces/[workspaceId]/invitations/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/invitations/route.ts`; `src/server/app-api/v1/workspaces/inputs.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `POST, DELETE /api/v1/workspaces/[workspaceId]/invitations/[invitationId]` — Resends or revokes a specific workspace invitation. Files: `src/app/api/v1/workspaces/[workspaceId]/invitations/[invitationId]/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/invitations/[invitationId]/route.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `PATCH, DELETE /api/v1/workspaces/[workspaceId]/members` — Changes a member role/status/ownership or removes a member, enforcing personal-workspace and manager invariants. Files: `src/app/api/v1/workspaces/[workspaceId]/members/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/members/route.ts`; `src/server/workspaces/WorkspaceService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `POST, DELETE /api/v1/workspaces/[workspaceId]/teams` — Creates or removes a workspace team. Files: `src/app/api/v1/workspaces/[workspaceId]/teams/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/teams/route.ts`; `src/server/workspaces/WorkspaceService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `POST, DELETE /api/v1/workspaces/[workspaceId]/teams/[teamId]/members` — Adds or removes a principal from a workspace team. Files: `src/app/api/v1/workspaces/[workspaceId]/teams/[teamId]/members/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/teams/[teamId]/members/route.ts`; `src/server/workspaces/WorkspaceService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `DELETE /api/v1/workspaces/[workspaceId]/lifecycle` — Performs the workspace lifecycle deletion/archive operation after ownership and policy checks. Files: `src/app/api/v1/workspaces/[workspaceId]/lifecycle/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/lifecycle/route.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `GET /api/v1/workspaces/[workspaceId]/management` — Returns manager-facing workspace membership, policy, and operational management data. For browser sessions it also repairs the current human principal from the authenticated profile before returning the People row, so legacy provider-ID labels are replaced by the person’s current name. Files: `src/app/api/v1/workspaces/[workspaceId]/management/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/management/route.ts`; `src/server/workspaces/WorkspaceService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `GET, PATCH /api/v1/workspaces/[workspaceId]/policies` — Reads or updates workspace policy/configuration after manager authorization. Files: `src/app/api/v1/workspaces/[workspaceId]/policies/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/policies/route.ts`; `src/server/workspaces/WorkspaceService.ts`; `src/server/authorization/AuthorizationService.ts`.
* `GET, POST /api/v1/workspaces/[workspaceId]/governance` — Reads governance views (directory, exports, retention, metrics) or links/deprovisions directory identities. Files: `src/app/api/v1/workspaces/[workspaceId]/governance/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/governance/route.ts`; `src/server/governance/WorkspaceGovernanceService.ts`; `src/server/workspaces/WorkspaceService.ts`.
* `GET /api/v1/workspaces/[workspaceId]/audit-export` — Exports workspace audit evidence for an authorized manager/auditor. Files: `src/app/api/v1/workspaces/[workspaceId]/audit-export/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/audit-export/route.ts`; `src/server/admin/AuditService.ts`; `src/server/authorization/AuthorizationService.ts`.

## 11. Workspace billing and entitlement operations

* `GET, POST /api/v1/workspaces/[workspaceId]/billing` — Reads the workspace billing summary or initializes its workspace billing account/wallet; only owners/admins can initialize. Files: `src/app/api/v1/workspaces/[workspaceId]/billing/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/billing/route.ts`; `src/server/billing/WorkspaceBillingService.ts`; `src/server/billing/http.ts`.
* `POST /api/v1/workspaces/[workspaceId]/billing/checkout` — Creates a workspace subscription checkout for an authorized workspace manager; the billing account is derived server-side. Files: `src/app/api/v1/workspaces/[workspaceId]/billing/checkout/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/billing/checkout/route.ts`; `src/server/billing/WorkspaceBillingService.ts`; `src/server/billing/BillingCheckoutService.ts`.
* `POST /api/v1/workspaces/[workspaceId]/billing/top-ups` — Creates a workspace purchased-credit/top-up checkout for an authorized manager. Files: `src/app/api/v1/workspaces/[workspaceId]/billing/top-ups/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/billing/top-ups/route.ts`; `src/server/billing/WorkspaceBillingService.ts`; `src/server/billing/BillingCheckoutService.ts`.
* `POST /api/v1/workspaces/[workspaceId]/billing/portal` — Opens a workspace billing portal session for an authorized owner/admin without accepting a caller-selected billing-account ID. Files: `src/app/api/v1/workspaces/[workspaceId]/billing/portal/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/billing/portal/route.ts`; `src/server/billing/WorkspaceBillingService.ts`; `src/server/billing/BillingCustomerService.ts`.
* `POST /api/v1/workspaces/[workspaceId]/billing/verify` — Verifies workspace checkout/payment state against the server-derived workspace billing account. Files: `src/app/api/v1/workspaces/[workspaceId]/billing/verify/route.ts`; `src/server/app-api/v1/workspaces/[workspaceId]/billing/verify/route.ts`; `src/server/billing/WorkspaceBillingService.ts`; `src/server/billing/BillingCheckoutService.ts`.
* `GET /api/v1/subscription` — Returns effective subscription/entitlement state for the active workspace-aware payer; member reads can be shared while mutations remain manager-scoped. Files: `src/app/api/v1/subscription/route.ts`; `src/server/app-api/v1/subscription/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCustomerService.ts`.
* `GET, POST /api/v1/subscription/settings` — Reads or changes personal subscription/billing settings through the authenticated app API contract. Files: `src/app/api/v1/subscription/settings/route.ts`; `src/server/app-api/v1/subscription/settings/route.ts`; `src/server/billing/http.ts`; `src/server/billing/BillingCustomerService.ts`.

## 12. Providers, integrations, MCP servers, and extensions

* `GET, POST /api/v1/integrations` — Lists available integrations or performs the supported integration action for the current caller, subject to runtime capability and origin policy. Files: `src/app/api/v1/integrations/route.ts`; `src/server/app-api/v1/integrations/route.ts`; `src/server/integrations/IntegrationService.ts`; `src/server/capabilities.ts`.
* `GET, POST, PATCH, DELETE /api/v1/providers/connections` — Lists, creates, updates, or deletes BYOK/provider connections; credentials are stored through the server credential boundary and endpoint validation is enforced. Files: `src/app/api/v1/providers/connections/route.ts`; `src/server/app-api/v1/providers/connections/route.ts`; `src/server/auth/connections/preset-registry.ts`; `src/app/api/v1/providers/request-size.ts`; `src/server/ai/gateway/hosted-provider-kill-switch.ts`.
* `POST /api/v1/providers/connections/test` — Tests a new or existing provider connection, optionally discovering models, without exposing the submitted secret. Files: `src/app/api/v1/providers/connections/test/route.ts`; `src/server/app-api/v1/providers/connections/test/route.ts`; `src/server/auth/connections/preset-registry.ts`; `src/app/api/v1/providers/request-size.ts`; `src/server/ai/gateway/gateway-search-tools.ts`.
* `GET, POST, PATCH, DELETE /api/v1/mcps` — Lists, creates, updates, or deletes the caller’s MCP server definitions and connection metadata. Files: `src/app/api/v1/mcps/route.ts`; `src/server/app-api/v1/mcps/route.ts`; `src/server/tools/mcp-tools.ts`; `src/server/tools/mcp-oauth.ts`.
* `POST, DELETE /api/v1/mcps/oauth` — Starts or cancels an MCP OAuth authorization session for a configured MCP server. Files: `src/app/api/v1/mcps/oauth/route.ts`; `src/server/app-api/v1/mcps/oauth/route.ts`; `src/server/tools/mcp-oauth.ts`; `src/server/tools/mcp-tools.ts`.
* `GET, POST /api/v1/mcps/oauth/callback` — Consumes a single-use third-party OAuth state, verifies optional browser binding, exchanges the code, refreshes the MCP tool catalog, or renders a desktop confirmation gate before exchange. Files: `src/app/api/v1/mcps/oauth/callback/route.ts`; `src/server/tools/mcp-oauth.ts`; `src/server/tools/mcp-tools.ts`; `src/server/auth/session.ts`; `src/server/security/rate-limit.ts`; `src/server/admin/AuditService.ts`.
* `POST /api/v1/mcps/test` — Tests an MCP server connection/tool catalog for the authorized owner. Files: `src/app/api/v1/mcps/test/route.ts`; `src/server/app-api/v1/mcps/test/route.ts`; `src/server/tools/mcp-tools.ts`; `src/server/tools/mcp-schema-to-zod.ts`.
* `GET, POST, PUT, PATCH, DELETE /api/v1/extensions/[extensionId]/[...path]` — Proxies an allowed extension request to the extension handler with BFF authentication/context and extension-specific path/method policy. Files: `src/app/api/v1/extensions/[extensionId]/[...path]/route.ts`; `src/server/app-api/v1/extensions/route.ts`; `packages/overlay-extension-sdk/src/index.ts`; `src/server/tools/tools/exposure-policy.ts`.

## 13. AI generation, transcription, browser, and sandbox execution

* `POST /api/v1/generate-title` — Generates a conversation title from supplied context using the authorized model/billing policy. Files: `src/app/api/v1/generate-title/route.ts`; `src/server/app-api/v1/generate-title/route.ts`; `src/server/ai/gateway/gateway-search-tools.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/generate-tab-group-label` — Generates a concise browser tab-group label from the supplied tabs/context. Files: `src/app/api/v1/generate-tab-group-label/route.ts`; `src/server/app-api/v1/generate-tab-group-label/route.ts`; `src/server/ai/gateway/gateway-search-tools.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/generate-image` — Generates an image through the allowed image model, stores the output, and returns the generated-output reference. Files: `src/app/api/v1/generate-image/route.ts`; `src/server/app-api/v1/generate-image/route.ts`; `src/server/outputs/OutputService.ts`; `src/server/storage/object-store.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/generate-video` — Generates a video through the allowed video model, stores the output, and returns the generated-output reference. Files: `src/app/api/v1/generate-video/route.ts`; `src/server/app-api/v1/generate-video/route.ts`; `src/server/outputs/OutputService.ts`; `src/server/storage/object-store.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/transcribe` — Transcribes an authorized audio upload/request through the configured speech provider and applies transcription billing/limits. Files: `src/app/api/v1/transcribe/route.ts`; `src/server/app-api/v1/transcribe/route.ts`; `src/server/billing/transcription-billing.ts`; `src/server/ai/gateway/gateway-search-tools.ts`.
* `POST /api/v1/browser-task` — Runs an authorized browser automation task with a bounded long-running request and capability gate. Files: `src/app/api/v1/browser-task/route.ts`; `src/server/app-api/v1/browser-task/route.ts`; `src/server/tools/tools/browser-executes.ts`; `src/server/capabilities.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/sandbox/run` — Runs a bounded command/job in the configured sandbox provider, handling uploads/downloads and billing policy. Files: `src/app/api/v1/sandbox/run/route.ts`; `src/server/app-api/v1/sandbox/run/route.ts`; `src/server/capabilities.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `POST /api/v1/daytona/run` — Runs a bounded Daytona sandbox task with lifecycle, artifact, and cost controls. Files: `src/app/api/v1/daytona/run/route.ts`; `src/server/app-api/v1/daytona/run/route.ts`; `src/server/app-api/v1/daytona/run/lifecycle.ts`; `src/server/app-api/v1/daytona/run/sandbox-runner.ts`; `src/server/ai/sandbox/daytona.ts`; `src/server/billing/billing-runtime.ts`; `src/server/capabilities.ts`.
* `POST /api/v1/notebook-agent` — Runs the notebook-agent workflow with notebook-specific tools and bounded model execution. Files: `src/app/api/v1/notebook-agent/route.ts`; `src/server/app-api/v1/notebook-agent/route.ts`; `src/server/agent/notebook-agent-stream.ts`; `src/server/ai/gateway/gateway-search-tools.ts`; `src/server/billing/ServerProviderUsageMeter.ts`.
* `GET /api/v1/link-preview` — Fetches and sanitizes a remote URL’s embeddable link-preview metadata under the route’s URL/SSRF and response-size policy. Files: `src/app/api/v1/link-preview/route.ts`; `src/server/app-api/v1/link-preview/route.ts`; `src/server/app-api/v1/link-preview/embeddable.ts`; `src/server/security/ssrf.ts`.

## 14. Slack import and onboarding

* `GET, POST /api/v1/imports/slack` — Reads Slack import status/configuration or starts the authenticated import request. Files: `src/app/api/v1/imports/slack/route.ts`; `src/server/app-api/v1/imports/slack/route.ts`; `src/server/imports/slack/composioClient.ts`; `src/server/imports/slack/backfillWorker.ts`; `src/server/capabilities.ts`.
* `POST /api/v1/imports/slack/process` — Internal/long-running Slack backfill worker callback that processes the queued import synchronously for the cron caller. Files: `src/app/api/v1/imports/slack/process/route.ts`; `src/server/app-api/v1/imports/slack/route.ts`; `src/server/imports/slack/backfillWorker.ts`; `src/server/shared/internal-api-secret.ts`.
* `GET /api/v1/onboarding/status` — Returns the current user’s onboarding completion/status view. Files: `src/app/api/v1/onboarding/status/route.ts`; `src/server/app-api/v1/onboarding/status/route.ts`; `src/server/onboarding/OnboardingRepository.ts`; `src/features/auth/lib/onboarding-cookie.ts`.
* `POST /api/v1/onboarding/complete` — Marks onboarding complete and records the associated user/profile state. Files: `src/app/api/v1/onboarding/complete/route.ts`; `src/server/app-api/v1/onboarding/complete/route.ts`; `src/server/onboarding/OnboardingRepository.ts`; `src/features/auth/lib/onboarding-cookie.ts`.
* `POST /api/v1/onboarding/reset` — Resets onboarding state for the authenticated user according to the server policy. Files: `src/app/api/v1/onboarding/reset/route.ts`; `src/server/app-api/v1/onboarding/reset/route.ts`; `src/server/onboarding/OnboardingRepository.ts`.

## Monitoring and security test index

The highest-value route families for separate dashboards and security test suites are:

* **Authentication/identity:** all `/api/auth/**`, `/api/better-auth/[...all]`, `/api/account/delete`, and `/api/v1/discovery`; monitor 401/403/409/429 rates, redirect destinations, PKCE/state replay, cookie mutation, and account-deletion audit events.
* **Secrets and object access:** `/api/auth/desktop-link`, `/api/auth/convex-token`, `/api/share/file/[token]`, `/api/v1/files/**`, `/api/v1/outputs/**`, and remote artifact routes; test token replay, owner/path binding, expiry, response caching, content-type confusion, and cross-tenant IDs.
* **Internal callbacks:** `/api/v1/automations/run`, `/api/v1/automations/execute`, `/api/v1/files/ingest-jobs/process`, `/api/v1/imports/slack/process`, `/api/v1/agent-environments/artifacts/cleanup`, and `/api/v1/agent-environments/operations/reconcile`; monitor internal-secret/service-auth failures, replay nonce failures, runtime duration, and unexpected public reachability.
* **Host control plane:** `/api/v1/agent-environments/**`; test signature canonicalization, method/path/body binding, timestamp/nonce replay, environment/workspace binding, credential rotation, command/event ordering, artifact scope, and rate-limit behavior.
* **Authorization/admin:** `/api/v1/admin/**`, `/api/v1/api-keys`, grants/shares, workspace membership, project/knowledge grants, and MCP/provider routes; monitor denied actions and audit-write failures, and test horizontal/vertical authorization with both session and API-key callers.
* **High-cost execution:** `/api/v1/conversations/act`, automation run/execute routes, `/api/v1/browser-task`, `/api/v1/sandbox/run`, `/api/v1/daytona/run`, media/transcription, knowledge search, and provider/MCP tests; monitor duration, provider failures, reservation/finalization mismatch, output size, and 429/5xx rates.
* **Realtime/streaming:** conversation Act, AgentRun, automation event/stream, and Postgres conversation events routes; monitor connection duration, first-byte/first-token latency, disconnect/reconnect observations, cursor replay, terminal persistence, and stale-run frequency.
* **Contract/documentation drift:** compare this catalog against `docs/openapi/overlay-web.openapi.json`, `src/shared/schemas/api-boundary.ts`, and `packages/overlay-api-client/src/index.ts`; in particular, verify the current API-key implementation and the documented `GET /api/v1/files/presign` contract.

## Maintenance rule

When adding, removing, or moving an app route, update this catalog in the same change and update `docs/develop/api-source-of-truth.mdx` if the transport/domain contract changes. Re-run a filesystem count and route-path comparison; do not rely on the OpenAPI file alone for coverage.