The @executor-js/api package provides the standard HTTP interface for the Executor platform. It defines a structured set of API groups using the Effect HttpApi framework, allowing hosts (CLI, Local, Desktop, Cloud) to expose a consistent management and execution surface.
The API layer is organized into Handler Groups that correspond to the core domain entities of the system. It follows a "Scoped Executor" pattern, where every request is associated with a specific tenant/owner context before reaching the business logic.
The API is built by composing multiple HttpApiGroup definitions into a single CoreExecutorApi packages/core/api/src/api.ts12-25 Hosts can further extend this by adding plugin-specific routes using addGroup packages/core/api/src/api.ts30
| API Group | Responsibility | Endpoint Prefix |
|---|---|---|
| Tools | Catalog discovery and schema inspection | /tools |
| Integrations | Management of plugin sources (OpenAPI, MCP, etc.) | /integrations |
| Connections | Instance-specific auth and configuration | /connections |
| Executions | Starting, pausing, and resuming tool calls | /executions |
| OAuth | OAuth2 flow orchestration and callbacks | /oauth |
| Policies | Access control and approval rules | /policies |
| Account | Organization and user profile management | /account |
Sources: packages/core/api/src/api.ts1-34 packages/core/api/src/index.ts19-24 packages/core/api/src/server.ts2-11
To support multi-tenancy and local isolation, the API relies on the ExecutorService packages/core/api/src/services.ts1 Instead of a global singleton, handlers access an executor instance provided via the Effect context. This instance is typically "scoped" to the current request's organization or user context by makeScopedExecutor packages/core/api/src/server.ts55-64
The API implements a uniform error translation layer to ensure internal implementation details (like database stacks or raw plugin errors) do not leak to the client.
capture(eff): A translator that catches StorageFailure and UniqueViolationError. It records the underlying cause via an ErrorCapture service and returns an opaque InternalError with a traceId to the client packages/core/api/src/observability.ts88-100InternalError: The public 500 error schema containing only a traceId packages/core/api/src/observability.ts9-11observabilityMiddleware: A safety net that catches defects (unexpected crashes) at the edge of the HTTP app packages/core/api/src/observability.ts150-164Sources: packages/core/api/src/observability.ts1-148
The following diagram illustrates how a tool schema request flows from a client through the API layer to the underlying SDK.
Tool Schema Request Flow
Sources: packages/core/api/src/tools/api.ts79-85 packages/core/api/src/handlers/tools.ts41-52
The API handles the complexities of the OAuth2 "dance," particularly for local and desktop hosts where the redirect must bridge back from a system browser to the application.
When an OAuth flow completes, the server renders a popupDocument packages/core/api/src/oauth-popup.ts77-80 This document is a dependency-free HTML page that attempts three methods to communicate the result back to the opener:
window.opener.postMessage packages/core/api/src/oauth-popup.ts119BroadcastChannel packages/core/api/src/oauth-popup.ts120localStorage event fallback packages/core/api/src/oauth-popup.ts121To support "Dynamic Client Registration" and strictly validated redirect URIs, the API provides a makeOAuthClientIdMetadataRoute packages/core/api/src/server/oauth-client-metadata.ts160-162 This serves RFC 7591-compliant metadata documents that allow providers to verify the client_id (which is the URL of the metadata document itself) and the allowed redirect_uris packages/core/api/src/server/oauth-client-metadata.ts122-158
OAuth Code Redemption Flow
Sources: packages/core/api/src/oauth-popup.ts128-156 packages/core/api/src/server/oauth-client-metadata.ts17-26 packages/core/api/src/server/oauth-client-metadata.test.ts6-24
Hosts mount the API by providing the necessary environment services. For example, the apps/local host uses startServer to wire the API to a Bun-based HTTP server.
/api and /mcp routes, while exempting health checks and OAuth callbacks apps/local/src/serve.test.ts151-182index.html for extension-less paths, enabling React-based SPA routing apps/local/src/serve.test.ts75-84startServer acquires a lock on the SQLite database and releases it upon shutdown apps/local/src/serve.test.ts88-100Sources: apps/local/src/serve.test.ts1-196 packages/core/api/src/server/executor-app.ts1-123
Refresh this wiki