Routes

Path mapping

The file's path under routes/ becomes the sub-path, minus the extension. Nested directories nest, and an index file maps to the directory itself:

.js wins over .ts for the same basename (compiled-binary semantics), and a direct file wins over an index file for the same path.

Writing a handler

Each file exports one function per HTTP method it accepts (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), using the standard Web API Request/Response signature. A request whose method the file does not export returns 405 with an Allow header listing the methods it does.

export async function GET(request: Request): Promise<Response> {
  return Response.json({ ok: true });
}

export async function POST(request: Request): Promise<Response> {
  const body = await request.json();
  return Response.json({ received: body }, { status: 201 });
}

Handlers receive a second contextargument with the Assistant's runtime singletons (the event hub, and a conversations.postMessage helper for surfacing an inbound event as a real turn):

export async function POST(request: Request, context): Promise<Response> {
  const { conversationId, text } = await request.json();
  await context.conversations.postMessage(conversationId, text);
  return Response.json({ delivered: true });
}

A handler may also reach other Assistant capabilities through its @vellumai/plugin-api imports, the same as any other surface.

Loading and lifecycle

Route files are loaded lazily on the first matching request and cached by path + mtime. Editing a route file is picked up on the next request; the dispatcher re-reads it when its mtime changes, so there is no restart or reload step. A handler that throws returns 500; a handler that runs longer than the per-request timeout (30s) returns 504.

Anatomy of a route

my-plugin/
└── routes/
    ├── index.ts          → GET /x/plugins/my-plugin
    ├── status.ts         → GET, POST /x/plugins/my-plugin/status
    └── webhooks/
        └── incoming.ts   → POST /x/plugins/my-plugin/webhooks/incoming

// routes/status.ts
export async function GET(request: Request): Promise<Response> {
  return Response.json({ status: "ok", uptimeMs: performance.now() });
}

Calling a route from an app frontend

A plugin app that backs its data with the plugin's own routes must reach them through the window.vellum.fetch bridge — never the global fetch. An app runs in a sandboxed origin, so a raw fetch carries no gateway URL and no auth headers and the request fails; window.vellum.fetch injects both and routes the call to the Assistant runtime.

Call the route at the same path it is served — /x/plugins/<name>/<path>. The wrapper prepends the /v1 API prefix for you, so you never write it:

// inside apps/<app>/src — calling this plugin's own status route
const res = await window.vellum.fetch("/x/plugins/my-plugin/status");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

Authenticated callers (the plugin's own app, local tools) reach the same route over HTTP. Third-party vendors on the public internet must go through plugin ingress instead; the window.vellum.fetchrule is specific to an app frontend's sandboxed origin.

When should my assistant write a Route?

Reach for a route when something already inside the assistant needs to call in over HTTP: an app frontend, a local tool, or a status endpoint. Unlike a tool (which the model calls) or a hook (which fires inside the turn), a route is driven by a caller and runs whenever a request arrives. If the caller is a third party on the public internet, also declare plugin ingress so the gateway can signature-check the request before it reaches this handler. Bundle both in a plugin when you want that endpoint to ship, version, and install alongside the plugin's other surfaces.