Custom Endpoints

Endpoints let a Space expose a published Flow at a caller-chosen HTTP method and path. They are the programmatic counterpart to Experiences: where an Experience renders a UI at a path, an Endpoint returns a JSON body at a path.

What an Endpoint Is

An Endpoint belongs to a Space and has:

• Method — one of GET, POST, PUT, PATCH, DELETE.
• Path template — the caller-chosen path as a simplified Endpoint path template, for example tasks/{taskId}/update-status. Each {param} segment is a typed path parameter: it carries a schema (the type the incoming value must validate against), which is the source of truth for that path param's type.
• Param schema — declares the Endpoint's query/body inputs. Each input is a scalar, validated against a Schema field. Path params are not declared here; they come from the path template.
• Request contract — maps each declared query/body param to one or more locations (query, body) and marks it required. Path params are derived from the template and are always required.
• Handler — flow, pointing at a published Flow in the Space.
• Response contract — the response source (contract, the default: the fixed status and body below; or flow: the first Endpoint - Respond node the run reaches, with the fixed status and body as the fallback), the HTTP status (200–599; no body is sent for 204, 205, and 304), content type, and either a body object whose values are literal, flow:result (a node's output), or context (run metadata), or a single root value of the same kinds that becomes the whole response body (for example, returning a Flow result array or string directly). When root is set, body is ignored. A per-Endpoint timeout (default 30s, max 300s) bounds how long the handler waits for referenced outputs.
• Status — draft, published, or retired. Publishing requires the handler Flow to have a published version. Only one Endpoint per method + route may exist at each status (path variable names don't distinguish routes); a conflicting create, update, or publish is rejected with 409.

How a Request Is Served

1. The front door (public App or Studio preview) resolves the Endpoint for the Space + method + path. Public serves published Endpoints only; preview serves a matching draft Endpoint first (even if a published route is more specific), falling back to published only when no draft matches.
2. The caller must be allowed to execute the handler Flow, exactly as for a direct run of the Flow: a built-in Space role, or a Space role capability granting execute on that Flow (App callers get their Space identity's role: the authentication strategy's default role, for example Guest, or the role of a pre-configured identity). Otherwise the request is treated exactly like an unmatched path (404), so the Endpoint's existence isn't revealed.
3. Request params are mapped from their declared locations and validated.
4. The published Flow version runs.

5. The response depends on the response contract's source:

   • contract (Fixed response, the default): when the referenced outputs are all present (or the run ends, or the budget is exhausted) the response body is assembled and returned with the contract's status.
   • flow (Controlled by flow): the first Endpoint - Respond node the run reaches is the response (status, headers, and body). See How to Redirect and Set Cookies from an Endpoint. Response nodes inside child Flows don't count. If the run ends without reaching one, the contract's status and body are the fallback. An invalid response (for example a body that doesn't match its declared type) returns 500 with { status: "invalid_response", flowExecutionId, message }, and the reason is logged on the run.

   On timeout the declared timeout shape is returned with HTTP 504; the run is never cancelled.

Dispatch errors map to their HTTP status (400 for invalid params or a malformed JSON body, 404 when no published Flow version exists, 500 for internal failures). On the public App, Endpoints take precedence over Experiences on the same path, so the response is the raw JSON body (never an HTML page), any method is accepted, and Endpoint paths may contain file extensions (for example, reports/data.json).

Front Doors

• Public (App) — https://{space}.{base}/{path}. Serves published Endpoints. The Space needs at least one authentication strategy; without one, the App returns 404 for every request on the Space (Studio shows a warning on the Endpoint page). When the Space has JWT strategies, a request with Authorization: Bearer <jwt> is authenticated by that token on every request, and an invalid token gets 401; see How to Authenticate Requests with a JWT.
• Preview (Studio) — /spaces/{spaceId}/endpoints/{path}. Serves draft Endpoints (falling back to published) so authors can test before publishing.

Management

Endpoints are managed in Studio under Space Settings → Endpoints. The Endpoints tab is hidden, and its pages are blocked, when the feature is not enabled.

Creating an Endpoint requires a plan that includes Endpoints (Team and Enterprise). Without it, creation fails with 402 PAYMENT_REQUIRED (ENTITLEMENT_REQUIRED cause) and the create page shows an upgrade prompt. Existing Endpoints can still be viewed, edited, published, retired, and removed.

The create and edit form configures:

• Path — edited as a single-line template: literal text plus Flow inputs inserted as variables (shown elsewhere as tasks/{taskId}/update-status). Literal text may contain letters, digits, -, ., _, ~, and /; each variable must be a whole path segment.
• Parameters — derived from the selected Flow's published trigger inputs. A path variable takes its type from the trigger input of the same name (string, number, or boolean; anything else matches as a string). Every other input can be exposed and accepted from the query string, the JSON body, or both, and marked required. Inputs of data type entity are accepted as a Record ID. When editing a saved Endpoint, trigger inputs added to the Flow later stay hidden until you expose them.
• Response — the Source: Fixed response (the default) or Controlled by flow. In Controlled by flow mode the form lists the published Flow's Endpoint - Respond nodes with their statuses, each linking to its place on the Flow editor canvas (?node={nodeId} on the Flow editor URL), warns when the Flow has none, and the settings below become the Fallback. Then the HTTP status (200–599; for 204, 205, and 304 no body is sent and the body settings are hidden), timeout, and body fields. Each field is a result node, a run context value, or a fixed value (text, number, or JSON). Choosing a Flow suggests one field per result node. Set Body to Single value as the whole body to return one value as the root of the response instead of an object.

The Flow must have a published version before its parameters and response can be configured. Edits to a published Endpoint take effect immediately.

OpenAPI

Each Space emits an OpenAPI 3.0.3 spec from its published Endpoints. The spec is available to Space admins at /spaces/{spaceId}/settings/endpoints/openapi.json (linked as OpenAPI spec on the Endpoints settings tab). It is the source of truth for external consumers.

The spec is titled with the Space title and lists these servers:

• {protocol}://{space name}.{app base hostname}: published Endpoints on the App, if the Space has a name. It uses the cloud's protocol, so http locally and https when deployed.
• https://{domain} for each verified custom domain, primary domain first: published Endpoints.
• {cloud base URL}/spaces/{spaceId}/endpoints: Studio preview. It serves drafts before published Endpoints and requires a Space admin session.

Each operation's responses:

• Fixed response: the contract status (no content for 204, 205, and 304) and 504.
• Controlled by flow: each literal status of the Endpoint - Respond nodes in the handler Flow's latest published version, with the node's declared body type; a default response when any node's status is dynamic; the contract status as the fallback; and 504. Different bodies for the same status are combined with oneOf.
• 3xx responses declare a Location header.

Export / Import

Endpoints are part of the Space export/archive. On import, Flow and Schema references are remapped to the target Space's IDs; an Endpoint whose referenced Flow was not imported fails the import.