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.tsfile. The inventory contains 196 route entry points: 34 non-versioned routes and 162/api/v1routes. 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/v1requests pass throughsrc/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.tsis 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 with410; 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;roleIdchanges 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.POSTaccepts an optionalvisibility(creatorfor Only me,workspacefor Everyone; defaults toworkspace).GETonly 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.PATCHaccepts an optionalvisibilityflip. 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/runtimeandworkflow/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/runtimeandworkflow/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 browserdisconnectedorreconnectedobservation 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 sendx-overlay-workspace-idrather 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 sendx-overlay-workspace-idrather 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 (acceptsarchivedquery flag; defaults to active projects), creates a project, updates project metadata/instructions/tree relationships/archive state (archivedboolean), 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, andpackages/overlay-api-client/src/index.ts; in particular, verify the current API-key implementation and the documentedGET /api/v1/files/presigncontract.
Maintenance rule
When adding, removing, or moving an app route, update this catalog in the same change and updatedocs/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.