Skip to main content
A workflow is one file in an app’s src/api/ directory that default-exports createEndpoint from zitejs/backend: server-side logic with typed inputs and outputs.
Each workflow must be a default export, and the filename is the workflow id, a single segment matching ^[a-zA-Z0-9_-]+$ (no subfolders under src/api/).

Config

inputSchema does not reject bad input. Input that fails the schema still reaches execute exactly as sent: missing required fields stay missing, and no defaults are filled in. When the input passes, top-level .default()s are filled in, and unknown keys are kept. Check required values in execute, as the example above does with subject.

Context

execute receives a context: id and email are always present when a user is signed in. name and image are never sent to a workflow.
context.user can be null even where the type says it cannot. The type only widens to allow null on workflows that declare a schedule or webhook. At runtime it is also null for an anonymous caller on a workflow without authenticated: true. Reading context.user.email there compiles cleanly and throws. Set authenticated: true when you need a user, or null-check regardless of the type.
process.env.ZITE_APP_URL is set to your app’s public URL. Use it to build links instead of hardcoding.

Errors

Throw ZiteError to return a controlled error. The platform maps its code to an HTTP status:
A positional form, new ZiteError('Not found', 'NOT_FOUND'), also works and defaults the code to 'INTERNAL_ERROR', but the object form above is preferred. Anything that is not a ZiteError, including an error carrying only a numeric statusCode, returns a 500.

Calling workflows from the frontend

Workflows are called through a generated, typed client (like tRPC). Each workflow exports a camel-cased caller plus its input/output types:
After adding, renaming, or deleting a workflow file, regenerate the client with npx zitejs generate from the workspace root (the build tools do this for you). Workflows are also reachable publicly at POST https://workflows.zite.com/public/{flowId}/api/{name}, with the input sent as { "inputs": { ... } }. Other methods get a 405, and a workflow with authenticated: true returns 401 to a caller with no session.

Streaming

Set stream: true and write chunks as you go:
On the frontend, streaming workflows are called with the generated streaming caller, which yields chunks and resolves a final result.