Server handlers

Routes your app exposes

Route	Used by	Purpose
`POST /api/a2a`	`A2AChat`, `A2AChatFloating`	Forwards chat messages to the agent and streams the reply back.
`GET /api/a2a/config`	`A2AChat`, `A2AChatFloating`	Returns the agent card, `nebulasProjectId`, `brandCss` and streaming support.
`POST /api/nebulas-surfaces/{id \| by-name/{name}}/render`	`NebulasSurface`	Builds a widget.
`POST /api/nebulas-surfaces/{id \| by-name/{name}}/actions/{action}`	`NebulasSurface`	Submits an action (runs its handler).
`GET /api/nebulas-surfaces/{id \| by-name/{name}}/theme.css`	`NebulasSurface`	The widget’s brand theme.
`* /api/nebulas/[...path]`	`A2AChat` with `nebulasBaseUrl`	Catch-all Nebulas proxy for conversation records. Session only.

Next.js (`@gnomondigital/nebulas-kit-core/nextjs`)

Export	Route	Auth
`createA2AProxyHandlerWithServiceAuth({ apiKey?, strategy? })`	`/api/a2a` (POST)	The app’s service credential
`createA2AProxyHandler({ auth0, audience?, apiKey? })`	`/api/a2a` (POST)	The user’s Auth0 session
`handleA2ANextJsPOST(request)`	`/api/a2a` (POST)	Strategy from config
`handleA2AConfigNextJsGET(request, { getHeaders })`	`/api/a2a/config` (GET)	Whatever `getHeaders` returns
`createGetHeadersWithServiceAuth({ apiKey?, strategy? })`	helper	Service credential → headers
`createGetHeadersForSession({ authClient, audience?, apiKey? })`	helper	Session → headers
`createSurfaceHandlerWithServiceAuth({ apiKey?, cache?, strategy? })`	`/api/nebulas-surfaces/[...path]`	Service credential
`createSurfaceHandler({ auth?, audience?, apiKey?, requireSession?, cache? })`	`/api/nebulas-surfaces/[...path]`	API key, or session when `auth` is set
`createNebulasProxyHandler({ auth, audience?, apiKey? })`	`/api/nebulas/[...path]`	Session (required)

Express (`@gnomondigital/nebulas-kit-core/express`)

Export	Mount at	Notes
`createA2AExpressRouter(express, { strategy?, apiKey?, getSessionToken?, configGetHeaders? })`	`/api/a2a`	Serves `POST /` and `GET /config`.
`createNebulasSurfaceRouter(express, { apiKey?, getHeaders?, cache? })`	`/api/nebulas-surfaces`	Same allowlist as Next.js.

Call app.use(express.json()) before mounting the routers.

Shared (`@gnomondigital/nebulas-kit-core`)

Export	Purpose
`configureNebulasServer(config)`	Sets the runtime config. Calling it again merges the new values in. See Configure the server.
`getAuthHeaders({ strategy, apiKey })`	Headers for a strategy, for your own Nebulas calls.
`getCachedServiceToken()`	The cached service token.
`resolveNebulasProjectId()`	Resolves the project the way the config endpoint does.
`resolveNebulasBrand()`	Resolves the brand CSS the way the config endpoint does.

Surface cache options

cache on the surface handlers:

Option	Default	Description
`enabled`	`false`	Turn caching on.
`freshMs`	`3000`	Time during which a cached render is returned without checking whether the widget changed.

Submissions (actions) are never cached.