API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
- apps/web/src/app/api/v1/invoke/route.ts
- apps/web/src/app/api/workflow/invoke/route.ts
- apps/web/src/app/api/evolution/[run_id]/route.ts
- apps/web/src/app/api/trace/[wf_inv_id]/node-invocations/route.ts
- apps/web/src/app/api/lockbox/secrets/route.ts
- apps/web/src/lib/api/schemas.ts
- apps/web/src/lib/api/README.md
- packages/mcp-server/src/index.ts
- tests/integration/api/v1/invoke.spec.test.ts
The API layer serves as the primary HTTP interface for the Lucky platform, enabling interaction with core functionalities like workflow execution, evolution tracking, and data management. It is built as a type-safe layer within the Next.js application, leveraging Zod schemas as the single source of truth for request and response contracts. This ensures runtime safety through validation and compile-time safety through TypeScript inference, minimizing type drift between the client and server.
The API is structured around distinct functional areas, including workflow invocation, evolution run monitoring, trace data retrieval, and secure secret management. A key endpoint, /api/v1/invoke, is designed to be compliant with the Model Context Protocol (MCP), facilitating standardized communication for agentic workflows. This architecture provides a robust, maintainable, and developer-friendly way to expose the platform's powerful backend services.
Sources: apps/web/src/lib/api/README.md
Core Architecture & Type Safety
The API's architecture is designed to enforce end-to-end type safety with minimal boilerplate. This is achieved by centralizing all API contracts in a single file and using helper utilities for validation and response formatting.
Sources: apps/web/src/lib/api/README.md
Architectural Flow
The diagram below illustrates the flow of a type-safe API request, from schema definition to client-server interaction.
This diagram shows the end-to-end type-safe API pattern, where Zod schemas are the single source of truth for both server-side request/response validation and client-side type inference.
Sources: apps/web/src/lib/api/README.md:14-23
Schema Definition
All API endpoint request and response shapes are defined in apiSchemas. Zod schemas from the @lucky/shared/contracts package are reused and extended to avoid duplication. This file acts as the single source of truth for the entire API layer.
Sources: apps/web/src/lib/api/schemas.ts:1-13, apps/web/src/lib/api/README.md:9-12, 51-58
Standardized Responses
API responses follow a standardized envelope to ensure consistency for both successful and failed requests. The ApiResponse type is a union of a success or failure envelope.
| Envelope | Structure | Description |
|---|---|---|
SuccessEnvelope | { success: true, data: T } | Wraps the successful response data. T is the Zod schema for the specific endpoint's data. |
FailureEnvelope | { success: false, error: ErrorEnvelope } | Provides a consistent error structure. |
ErrorEnvelope | { code, message, timestamp, details? } | Contains detailed information about an error. |
Sources: apps/web/src/lib/api/schemas.ts:18-44
Workflow Invocation Endpoints
These endpoints are central to executing workflows on the platform.
POST /api/v1/invoke
This is a public-facing, JSON-RPC 2.0 compliant endpoint designed for invoking workflows, making it compatible with the Model Context Protocol (MCP). It requires Bearer token authentication.
Sources: apps/web/src/app/api/v1/invoke/route.ts, apps/web/src/lib/api/README.md:120-122
Request Flow
The following diagram shows the sequence of operations when a request is made to /api/v1/invoke.
This sequence illustrates the v1/invoke endpoint processing a request, including authentication, validation, database interaction, and queuing the workflow run.
Sources: apps/web/src/app/api/v1/invoke/route.ts:16-100, tests/integration/api/v1/invoke.spec.test.ts:100-129
Parameters
The request body must be a valid JSON-RPC 2.0 object with the method workflow.invoke.
| Parameter | Type | Description | Required |
|---|---|---|---|
jsonrpc | string | Must be "2.0". | Yes |
id | string | number | A unique identifier for the request. | Yes |
method | string | Must be "workflow.invoke". | Yes |
params.workflow_id | string | The ID of the workflow to invoke. | Yes |
params.input | any | The input data for the workflow. | Yes |
params.options.goal | string | A description of the goal for this specific run. | No |
params.options.trace | boolean | If true, enables detailed execution tracing. | No |
params.options.timeoutMs | number | Maximum execution time in milliseconds. | No |
Sources: apps/web/src/lib/api/schemas.ts:60-63, tests/integration/api/v1/invoke.spec.test.ts:88-99
Error Handling
The endpoint returns standard JSON-RPC error codes.
| Code | Message | Cause |
|---|---|---|
| -32000 | Authentication failed | Missing, invalid, or expired API key. |
| -32600 | Invalid Request | Malformed JSON or request does not conform to the JSON-RPC spec. |
| -32602 | Invalid params | The params object is missing required fields or has invalid types. |
| -32001 | Workflow not found | The provided workflow_id does not exist or the user lacks permission. |
Sources: tests/integration/api/v1/invoke.spec.test.ts:131-180, apps/web/src/app/api/v1/invoke/route.ts:31-35, 52-56
POST /api/workflow/invoke
This is an internal-facing endpoint used by other parts of the application to invoke a workflow. It uses a standard RESTful approach rather than JSON-RPC.
Sources: apps/web/src/app/api/workflow/invoke/route.ts
| Parameter | Type | Description | Required |
|---|---|---|---|
workflowVersionId | string | The specific version ID of the workflow to run. | Yes |
evalInput | object | The input data, conforming to the EvaluationInputSchema. | Yes |
Sources: appsweb/src/lib/api/schemas.ts:69-72
Evolution & Tracing Endpoints
These endpoints provide visibility into the execution and evolution of workflows.
GET /api/evolution/[run_id]
Retrieves the details for a specific evolution run, including its configuration and status. This is used to monitor the progress and results of a genetic programming or iterative improvement process.
Sources: apps/web/src/app/api/evolution/[run_id]/route.ts
GET /api/trace/[wf_inv_id]/node-invocations
Fetches all node invocation records for a given workflow invocation ID (wf_inv_id). This is critical for debugging and visualizing the step-by-step execution of a workflow, showing the inputs, outputs, and costs of each agent (node) in the graph.
Sources: apps/web/src/app/api/trace/[wf_inv_id]/node-invocations/route.ts
Security Endpoints
POST /api/lockbox/secrets
This endpoint is responsible for securely creating or updating secrets in the user's lockbox, which is persisted in the database. It is used to manage API keys and other sensitive credentials required by workflows.
Sources: apps/web/src/app/api/lockbox/secrets/route.ts
MCP Server Integration
The lucky-mcp-server package provides a Model Context Protocol (MCP) server that exposes tools over a JSON-RPC 2.0 interface, similar to the /api/v1/invoke endpoint. This allows external systems, like IDEs (Cursor, VS Code) or other agents, to consume tools in a standardized way.
Sources: packages/mcp-server/README.md, packages/mcp-server/src/index.ts
MCP Tool Execution Flow
This diagram shows how an external client like an IDE uses the lucky-mcp-server to execute a workflow. The MCP server acts as a proxy, forwarding the request to the main application's /api/v1/invoke endpoint.
Sources: packages/mcp-server/src/index.ts:168-223
Summary
The API endpoints form a well-structured and type-safe interface to the lucky platform's core services. By leveraging Zod for schema definition and validation, the system ensures data integrity and a superior developer experience. The inclusion of a JSON-RPC 2.0 compliant endpoint (/api/v1/invoke) and a dedicated MCP server demonstrates a commitment to interoperability within the broader AI agent ecosystem. Endpoints for tracing and evolution provide essential observability, while security endpoints like the lockbox API ensure that sensitive data is handled correctly. This combination of features makes the API layer a robust and crucial component of the overall architecture.