How to Implement Real-Time Health Checks and Echo Endpoints in the OpenCut API

The OpenCut API exposes stateless GET endpoints at /health and /echo via the Hono router on Cloudflare Workers, enabling sub-millisecond health monitoring and request echoing for instant debugging.

The OpenCut backend, located in the OpenCut-app/OpenCut repository, leverages the Hono HTTP framework running on Cloudflare Workers to provide essential utility routes. These real-time health checks and echo endpoints require no persistent server process and respond instantly from the edge, making them ideal for production monitoring and client connectivity validation.

Route Registration in apps/api/src/index.ts

The core implementation resides in apps/api/src/index.ts, where the Hono application instance registers both utility routes using the .get() method.

The /health Endpoint

Line 6 of apps/api/src/index.ts defines the health check:

.get("/health", () => ({ healthy: true, timestamp: new Date().toISOString() }))

This returns a JSON object containing a boolean healthy status and an ISO 8601 timestamp generated fresh on each request. Because the code executes on Cloudflare Workers, the timestamp reflects the edge server's current time, ensuring accurate monitoring data.

The /echo Endpoint

Line 8 implements the echo service:

.get("/echo", (c) => c.req.query("msg") ?? "no message")

This extracts the msg query parameter from the request context (c.req.query) and returns it verbatim. If the parameter is omitted, it returns the fallback string "no message", preventing null values and ensuring consistent text responses.

Stateless Architecture and Performance

Both routes operate in a stateless manner within the Cloudflare Workers environment. Since there is no persistent server process, each request runs in isolation, guaranteeing that health checks never interfere with other workloads. The edge deployment ensures responses complete within a few milliseconds, suitable for high-frequency monitoring from tools like Grafana or Datadog.

Implementation Examples

Health Check Monitoring

Fetch the health status from Node.js or browser environments:

fetch("https://api.opencut.app/health")
  .then(res => res.json())
  .then(data => {
    console.log("Service healthy:", data.healthy);
    console.log("Timestamp:", data.timestamp);
  })
  .catch(err => console.error("Health check failed:", err));

Echo Endpoint Debugging

Test connectivity or measure latency by echoing custom messages:

const message = "Hello OpenCut!";
fetch(`https://api.opencut.app/echo?msg=${encodeURIComponent(message)}`)
  .then(res => res.text())
  .then(echoed => {
    console.log("Echoed back:", echoed); // → "Hello OpenCut!"
  });

Command-Line Testing

Use curl for monitoring scripts or quick checks:

# Health check with JSON parsing

curl -s https://api.opencut.app/health | jq .

# Simple echo test

curl -s "https://api.opencut.app/echo?msg=ping"

Configuration and Deployment Files

The utility routes rely on specific configuration files within the apps/api directory:

• apps/api/package.json: Declares the Hono runtime dependency and Cloudflare Workers configuration
• apps/api/wrangler.jsonc: Defines the Worker deployment settings; the /health and /echo routes become automatically exposed once the Worker publishes to the edge

These configuration files work in concert with the route definitions in apps/api/src/index.ts to deploy the real-time health checks and echo endpoints without additional infrastructure.

Summary

• The OpenCut API implements stateless health and echo endpoints using the Hono router in apps/api/src/index.ts
• The /health endpoint returns a JSON payload with a boolean status and ISO timestamp generated via new Date().toISOString()
• The /echo endpoint returns the msg query parameter or a fallback string "no message" using c.req.query("msg")
• Running on Cloudflare Workers, these routes execute in isolated serverless environments with sub-millisecond latency
• Configuration in wrangler.jsonc and package.json enables automatic edge deployment without persistent server management

Frequently Asked Questions

How do I customize the health check response format?

Modify the object returned in the /health route handler at line 6 of apps/api/src/index.ts. You can add additional fields such as version numbers or dependency statuses, but ensure the response remains lightweight to maintain the sub-millisecond response characteristic critical for real-time monitoring.

Why does the echo endpoint return "no message" instead of null?

The implementation uses the nullish coalescing operator (??) to return "no message" when the msg query parameter is absent. This design prevents null values from being serialized in the response, ensuring that clients always receive a valid string for display or logging purposes.

Can these endpoints handle high-frequency monitoring requests?

Yes. Because the OpenCut API runs on Cloudflare Workers, each health check executes in an isolated, serverless environment without consuming persistent resources. The stateless design and edge deployment allow the /health endpoint to handle thousands of concurrent checks without impacting video processing or other API workloads.

Where are the route handlers registered in the codebase?

The route handlers are registered in apps/api/src/index.ts using the Hono router's .get() method. The health endpoint is defined at line 6 and the echo endpoint at line 8, immediately following the Hono application initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}