Routing

HTTP routes are inferred from where a Flow file lives. Put http.get() in src/flows/notes/[id]/get.ts and the compiler stamps GET /notes/:id, names the Flow notes.get, and the client calls api.notes.get({ id }).

When to omit · when to pass

Consequence: most app code looks like the create-oke template — http.get().public() + flow({ … }) — with no string path and no string name.

Smallest Example

import "@/flows/generated";
import { oke } from "okengine";

export const app = oke({ name: "notes" });

import { on, flow, http } from "okengine";
import { z } from "zod";

export const get = on(
  http.get({
    in: z.object({ id: z.string() }),
    out: z.object({ id: z.string() }),
  }),
  flow({
    do: async ({ id }) => ({ id }),
  }),
);

curl -X GET http://localhost:6530/notes/n_1 -H "accept: application/json"

{
  "data": { "id": "n_1" },
  "error": null
}

Progressive Patterns

From a pathless tree file to an explicit barrel, an action leaf, and a catch-all:

import { on, flow, http } from "okengine";

export const list = on(
  http.get(),
  flow({
    do: () => [],
  }),
);

Convention Reference

Units

The first folder under src/flows/ is the client unit. Nested folders and the leaf file build the URL. The export const name is the method on that unit.

src/flows/
├── notes/                     # Unit: notes → api.notes.*
│   ├── list.ts                # GET /notes          (reserved leaf)
│   ├── create.ts              # POST /notes         (reserved leaf)
│   ├── shapes.ts              # skipped (not a route)
│   └── [id]/
│       ├── get.ts             # GET /notes/:id
│       └── archive.ts         # POST /notes/:id/archive
├── billing/
│   └── (checkout)/            # omitted from the URL
│       └── charge.ts          # POST /billing/charge  (if http.post())
└── main/                      # Unit: main — prefix omitted from the URL
    ├── health.ts              # GET /health
    └── route.ts               # GET /

A file sitting directly in src/flows/ (no unit folder) is not a route.

Unit folder names must be valid JS identifiers (notes, main, _ allowed inside; my-notes is skipped). Folders starting with _, [, or ( are not units.

Consequence: export const getNote from get.ts is api.notes.getNote, not api.notes.get. Match the export to the name you want on the client.

Path Conventions

Default — pathless. Omit the path so generated.ts stamps the URL from disk:

http.get(); // pending until stampHttpPath runs

Control — explicit path. Pass the URL template when the folder should not own the route (barrel, public API shape, resource mount). The tree never overwrites an explicit path:

http.get("/organizations/:orgId/members/:memberId");

Path params, query string, and JSON body still merge into one object checked by in — same order as HTTP · Request Parsing.

Dynamic parameters

[id] → :id. The folder name is the param key. Declare the same key on in:

import { on, flow, http } from "okengine";
import { z } from "zod";

export const get = on(
  http.get({ in: z.object({ orgId: z.string(), memberId: z.string() }) }),
  flow({
    do: async ({ orgId, memberId }) => ({ orgId, memberId }),
  }),
);

Stamped to GET /orgs/:orgId/members/:memberId.

Catch-alls

[...slug] → * (greedy rest). Optional [[...slug]] is not supported — generate fails with Optional catch-all "[[...slug]]" is not supported — use [...slug] (param is "*").

A route that includes * selects the Trie matcher automatically (the compiled RegExp matcher cannot express wildcards).

Route groups

A folder (ops) is omitted from the URL. Use it to group files without adding a segment:

src/flows/notes/(ops)/archive.ts  →  /notes/archive

(ops) never enters the Flow name either (notes.archive).

The main unit

main is omitted from the URL prefix. Flow names still use main.:

Skip list

These files are never routes (walk skips them; path inference returns nothing):

Skip-list files may sit next to tree routes. They do not turn a tree into a barrel.

Reserved Leaves

To avoid /notes/get and /orders/list, these filenames add no URL segment — the same five CRUD names as http.resource, plus folder roots:

Any other leaf is a segment: query.ts → /notes/query.

In a tree unit, do not add index.ts beside other route files — that is a generate error. Use route.ts (or list.ts / create.ts) for the collection root.

Barrel vs Tree

oke dev / oke build scans each src/flows/<unit>/ folder and writes generated.ts. Two shapes, never mixed:

const notes = {
  get: stampHttpPath(stampFlowName(notes_$id$_get.get, "notes.get"), "/notes/:id"),
  list: stampHttpPath(stampFlowName(notes_list.list, "notes.list"), "/notes"),
};
export { notes };
registerFlowUnits({ notes });

Unit "notes" mixes a barrel index.ts with tree route files. Use only index.ts (barrel), or move the collection path to route.ts and keep [id]/ beside it.

Unit "notes" exports "get" from both list.ts and route.ts.

flow("tasks.…") in notes/get.ts does not match the folder "notes".

Names

Three names, one file:

Nameless flow({ do }) is the tree default — same rule as pathless HTTP. Pass flow("notes.get") only for control (stable name, barrel, or matching unit prefix). Wrong-unit prefixes fail generate.

Non-HTTP files still join the unit. A signal consumer in notes/on-created.ts is api.notes.onCreated over RPC (POST /_oke/notes/onCreated), not HTTP.

Signal / Clock consumers pass an explicit flow("…") name (OKE1072 if nameless outside src/flows/<unit>/; OKE1070 on collision). Clock may write clock.every(…) inside on() — Clock · Inline or named export.

Runtime Matching

All adopted HTTP bindings go into one matcher. Wrong method on a known path is 405 with Allow. No match is a bare 404 Not Found.

p99 match stays under 1 ms on the compiled matcher. You do not pick buckets by hand — a catch-all in the table selects Trie for the whole app.

Duplicate METHOD + path fails boot (OKE1041), including a resource mount plus a handwritten http.get("/notes").

Troubleshooting

Learn more

• HTTP — verbs, envelopes, http.resource, live SSE
• Client — api.notes.get, REST vs RPC, $routes
• Errors — OKE1040 · OKE1030 · OKE1041 · OKE1045 · OKE1070 · OKE1072
• The Architecture — derived routes, no hand-written table
• Gate — .gate(...) / .public() on the same trigger

Next