API

apps/api runs on port 3002 and deploys as the Cloudflare Worker opb-brain-api.

What it serves today

Four route handlers, and nothing else.

It is separate from apps/app so that non-browser callers have an endpoint that does not carry the product shell, and so webhook and cron traffic scales independently of user traffic.

Where the agent doors go

This application is the intended home of three of the four interfaces. None of them exists yet.

All three are designed to sit on one service layer that owns validation, the task state machine and event writes, so no door can hold logic another lacks or bypass a transition guard.

Adding a route

A route handler is a route.ts exporting an HTTP method:

import { database } from '@repo/database';

export const GET = async () => {
  const pages = await database.page.findMany();

  return Response.json(pages);
};

That stub model is the only one available today. The domain tables described in the concepts pages do not exist.

Calling it from another application

NEXT_PUBLIC_API_URL is pre-configured in each application's .env.example, pointing at http://localhost:3002 locally.

Most of the time it is not needed. apps/app and apps/web are both Next.js applications and reach the database through @repo/database directly, in Server Components and Server Actions. Route a call through the API when the caller is not one of those applications, or when the work should be isolated from user-facing traffic.

Preview deployments

Each Worker gets its own preview URL from Cloudflare Workers Builds, and a preview of apps/app cannot discover the matching preview of apps/api. Two options, in order of how much isolation they give:

1. Point previews at the production API by setting NEXT_PUBLIC_API_URL for the preview environment.
2. Override NEXT_PUBLIC_API_URL per deployment.