Flowstack SDK Reference

Every hook, component, utility, and endpoint in the Flowstack SDK (v0.3.3). Generated from a single canonical model, so the human docs, the agent-readable corpus, the semantic graph, and the API contract never drift apart.

Machine-readable surfaces

Concise index for LLMs and coding agents.

Full corpus, one markdown doc per symbol.

Authoritative OpenAPI 3.1 for the full REST/SSE API.

The canonical model — for tooling & MCP.

Aggregated schema.org @graph of every entity.

search-index.json

Precomputed embeddings for semantic search.

agents-map.json

Casino sites with agents → reachable endpoints.

REST & SSE API

Call Flowstack over HTTP directly — 337 operations across the Sage Data Science Agent backend. The authoritative OpenAPI 3.1 contract is generated by the backend, not hand-written.

All endpoints →

Browse every endpoint grouped by area (288 paths).

The full machine-readable OpenAPI 3.1 spec.

Agent Map

Every Casino site with a registered agent — 29 agents across 19 sites — and how to reach each one.

Browse the agent map →

Sites, personas, capabilities, and reach endpoints.

agents-map.json

The machine-readable map for agents & tooling.

Built Apps

The generated-site pattern: provider, auth flow, and data operations for apps built on Flowstack.

FlowstackProvider

The root provider that wraps a built app and supplies backend config (baseUrl, tenantId, mode, appScope) to all Flowstack hooks.

The hook built apps use to read auth state — isAuthenticated, isInitialized, and credentials — instead of useAuth().

Read and send private messages within one DM thread in a built app.

Manage published sites — list, create, stage files, publish to CDN, and delete.

List a built-app user's private message threads, with unread counts and consent control.

Client function: activate a domain once its ACM cert is issued (CloudFront goes live ~5–15 min after).

clearStagedFiles

Client function: clear all staged files for a site (the .staging marker is preserved).

Client function: start connecting a custom domain — requests an ACM cert and returns the DNS records to add.

disconnectDomain

Client function: disconnect a custom domain from a site.

Pure helper: deterministic, order-independent thread key for a pair of user keys.

Client function: fetch a version's source files as a { path: content } map (live version by default).

Client function: get the saved mongoCollections schema (data plan) for a site.

getDomainStatus

Client function: poll a custom domain's validation/activation status.

Client function: list the custom domains connected to a site and their status.

Client function: list messages in the caller's thread with a counterpart. ACL'd server-side.

listStagedFiles

Client function: list the files currently staged for a site.

Client function: list the caller's DM threads (counterpart key, last message, unread count).

markMessageRead

Client function: mark a received DM as read (recipient only).

Client function: record the caller's consent to open a DM thread with another user.

Client function: buy a domain through Casino — returns a Stripe Checkout URL; registration + site auto-connect fire from the payment webhook (P0-163).

Client function: rename a site (display name in the manifest + dashboard metadata).

Client function: check domain availability + Casino retail pricing across TLDs (P0-163).

Client function: send a private message. 403 unless the thread is mutually open.

Client function: merge collection schemas into the site's data plan (PUT-with-merge).

Client function: stage multiple files in one call (batch form of addSiteFile).

CustomDomainRecord

Type: a connected custom domain and its lifecycle status.

A single private message within a DM thread.

A private message thread between the caller and one counterpart.

DomainSearchResult

One TLD's availability + Casino retail price from searchDomains (P0-163).

PurchaseDomainRequest

Request body for purchaseDomain: name + TLD + registrant contact + auto-renew/privacy/auto-connect options (P0-163).

RegistrantContact

WHOIS registrant contact for a domain purchase — registrar-validated formats (P0-163).

Authentication

Login, sessions, brokered login, and route guards.

Read and mutate Casino-platform auth state (login, register, Google sign-in, logout, token refresh).

Programmatic route protection that reports whether access is allowed and where to redirect.

Wrapper that renders children only when authenticated — showing a login fallback, or transparently issuing a guest session for opted-in built apps.

BrokeredLoginButton

The only authentication method for built apps — a button that opens Casino's auth popup where Privy runs and posts a scoped JWT back to the app.

Data

MongoDB-backed collections, public submissions, datasets, and queries.

Agent-Driven Data Models — Reason → Write → Read

The core pattern for using an agent as a worker: the app reads context and passes it in the prompt, the agent reasons and writes a structured document, and the app reads the result back via useCollection.

Two-layer data model — shared vs per-user

How useCollection and the agent's data tools resolve a collection to one of two namespaces — a physically isolated per-user database or a single world-readable shared pool — via the layer option.

form-write-direct

Save form submissions and simple CRUD deterministically — no LLM, no tokens, no streaming

library-import-analyze

Import a workspace library item (dataset, report, document, visualization) into the app's agent and analyze it

Give each signed-in user their own private data (notes, entries, history) isolated from every other user

scheduled-agent-report

Run an agent prompt on a cron schedule and surface its output in the app (daily digests, weekly reports)

Share one pool of data across all users of the app (leaderboards, feeds, catalogs), readable even before sign-in

Direct MongoDB CRUD for built-app data — the primary, reactive data hook for tables, forms, cards, and persistence.

useCollectionExplorer

Browse, query, export, and delete a specific MongoDB collection.

useDataOverview

Get a unified summary of all user-owned data.

List, upload, download, and delete datasets, with reactive loading and error state.

Manage external data source connections — create, test, delete, and list.

usePublicCollection

Anonymous, no-auth public collection reads and inserts for leaderboards, guestbooks, comment threads, and voting.

Run a single one-shot query from a natural-language prompt without streaming.

List generated reports with reactive loading and error state.

useUserCollections

List all MongoDB collections the user owns.

useVisualizations

List generated visualizations with reactive loading and error state.

AI & Agents

Streaming agent queries, personas, tool access, and the agent catalog.

There are no pre-built ecosystem agents — agents are per-app; you create them with casino_create_agent via the Casino MCP and target them by name.

Agent Templates & Factory

Pre-configured agent templates (data-science, marketing, support) plus a dynamic Agent Factory that routes user intent to the best registered agent.

Targeting Custom Agents (Built Apps)

Built apps target an agent they create via `casino_create_agent` by passing its registered name as `persona` — a target is required for app-scoped users or they get a 403.

Tool-level Access Control (P0-117)

Pass an explicit tools list to casino_create_agent for per-tool access control, which overrides category-level capabilities grants.

Available Tool Categories

The nine capability categories you declare on a registered agent (and, advisorily, on `useAgent`), each granting a group of related tools.

Run AI agent queries with streaming, tool calls, interrupts, status updates, and automatic conversation persistence.

Discover the agents available to the current site, including their name, description, tools, trigger phrases, and intended use.

useConversations

Fetch the user's past Casino builder conversations.

Create and manage agents dynamically based on user intent.

ML model management — list registered models with their framework, metrics, and creation metadata.

useOllamaDetection

Detect a local Ollama instance and list its available models.

useProviderCredentials

Manage LLM provider credentials (BYOK and Ollama).

useToolInvocation

Low-level hook for directly invoking an agent tool.

Workspaces & Users

Multi-tenant workspaces and user management.

useSiteVersions

Work with the version history of a published site.

useUserManagement

Admin hook to list, search, paginate, and mutate managed users plus view user stats and activity.

List, create, and select workspaces for the current user.

Components

Pre-built pages, forms, and rendering components.

Complete pre-built auth page with login/register tabs and optional Google sign-in.

Embeddable chat interface bound to an agent template.

Full pre-built chat interface page.

CreateWorkspaceModal

Modal dialog for creating a new workspace.

DashboardLayout

Pre-built dashboard layout with a sidebar, header, and content area.

DatasetUploader

File-upload component for ingesting datasets such as CSV, XLSX, and Parquet files.

Pre-built login form with success/error callbacks and an optional register link.

MarkdownRenderer

Drop-in component for rendering agent responses with full GFM support and automatic mid-stream table repair.

Renders a list of chat messages, with optional streaming state.

Pre-built registration form with a success callback and an optional login link.

WorkspaceSelector

Pre-built control for selecting the active workspace.

Wallet

The wallet module: balances, transactions, and payment components.

Separate `flowstack-sdk/wallet` entry point for the two token systems (AGENT build credits, INFER query credits): reading balances, accepting payments, and accessing wallet addresses.

Charge users of the app for access (unlock fee or metered queries) using the platform paywall

useAgentBalance

Poll the connected wallet's AGENT token balance so built apps can check whether the end-user can afford an operation.

Check whether the authenticated end-user has access to a monetized built app, and open Stripe Checkout to unlock it. Use directly only for custom gate UI — `AppPaywall` wraps this with a default overlay.

Open the fiat on-ramp widget to buy INFER tokens and track purchase status.

Deposit INFER tokens from the connected wallet and track the resulting transaction hash.

useInferBalance

Read the connected wallet's INFER token balance, including available balance and query credits.

Read wallet connection state and trigger Privy/SIWE login or logout from the `flowstack-sdk/wallet` entry point.

AgentBalanceBadge

Display badge showing the connected wallet's AGENT token balance.

Access gate for monetized built apps: renders children when the end-user has access, otherwise shows a paywall overlay with the unlock CTA. The default way to charge users of an app.

Modal for buying INFER tokens.

InferBalanceBadge

Display badge showing the connected wallet's INFER token balance.

Privy/SIWE login button for the Casino platform only — built apps use `BrokeredLoginButton` instead.

Gate a feature behind a minimum AGENT balance, showing a deep-linked "Get AGENT →" CTA when the user has insufficient funds.

PaymentRequired

Gate content behind payment, rendering children only once the requirement is met.

cancelAppSubscription

Client function: cancel an app subscription at period end (P0-162).

getBuilderEarnings

Client function: aggregate + per-app builder earnings across both rails (Stripe cents + on-chain AGENT).

getConnectStatus

Client function: live Stripe Connect account status for the builder (refreshes cached flags).

getMonetization

Client function: read a site's monetization (paywall) configuration.

requestBuilderPayout

Client function: withdraw the builder's available fiat balance to their connected Stripe account.

setMonetization

Client function: set a site's monetization (paywall) configuration.

startConnectOnboarding

Client function: create (or reuse) the builder's Stripe Connect Express account and get an onboarding link.

Client function: open Stripe Checkout for an app's monthly subscription plan (P0-162).

AppSubscriptionStatus

The end-user's subscription state for one app: status and billing period — status-only since 0.3.3/P0-167 (P0-162).

BuilderEarnings

Type: the builder's full earnings picture — both rails, self-query summary, per-app breakdown.

Type: the builder's Stripe Connect account state.

Type: a built app's monetization (paywall) config — Stripe and/or AGENT-token payment.

MonetizationSubscriptionConfig

Monthly subscription plan config: $X/month for full access on the builder's Stripe Connect rails — pure access revenue since 0.3.3/P0-167 (P0-162).

Integrations & Automations

Service connections, integrations, and automations.

call-http-integration

Use a registered HTTP API integration (notion, slack, linear, or owner-registered) from a built app via the agent

call-stripe-api

Operate on the OWNER's Stripe account (revenue dashboards, customer lookups, invoice ops) from a built app

connect-google-services

Let each user connect Google and use the sub-services their scopes actually grant (analytics, ads, drive, youtube)

connect-oauth-service

Let each user connect an OAuth service (github, reddit, twitter, strava, google) and work with their data in the app

Let each user connect their Strava account and work with their activities in the app

register-custom-api

Let the app OWNER register any HTTPS REST API as an integration the agent can call as a tool

Schedule agent prompts on a cron schedule (via AWS EventBridge) with silent, email, webhook, or file delivery.

Manage a user's external service connections (Google, Reddit, Strava, Twitter/X) so the AI agent can access their data.

useIntegrations

Register any HTTPS REST API as a named integration the agent can call as a tool, with credentials encrypted at rest.

Utilities

API client, streaming helpers, and cache utilities.

useFlowstackStatus

Monitor the backend connection status, latency, and connectivity with optional polling.

Lower-level promise-based API functions for direct backend access when hooks don't provide enough control.

Default time-to-live values for the SDK's per-resource client-side cache.

Remove a value from the generic per-resource client-side cache.

The low-level fetch escape hatch used by every API client function for authenticated requests to the Flowstack backend.

Read a value from the generic per-resource client-side cache.

getCachedDatasets

Read the cached list of datasets from the client-side cache.

getCachedReports

Read the cached list of reports from the client-side cache.

Read the cached list of sites from the client-side cache.

getCachedVisualizations

Read the cached list of visualizations from the client-side cache.

getCachedWorkspaces

Read the cached list of workspaces from the client-side cache.

invalidateAllUserCache

Clear the entire client-side cache for the current user.

invalidateDatasetsCache

Invalidate the cached list of datasets.

invalidateReportsCache

Invalidate the cached list of reports.

invalidateSitesCache

Invalidate the cached list of sites.

invalidateVisualizationsCache

Invalidate the cached list of visualizations.

invalidateWorkspaceArtifacts

Invalidate all cached artifacts (datasets, visualizations, reports, etc.) for a workspace.

invalidateWorkspacesCache

Invalidate the cached list of workspaces.

Parse a single Server-Sent Events line into a typed StreamEvent.

Async generator that yields typed StreamEvents from an agent SSE Response.

processSSEStream

High-level helper that drives an agent SSE Response through callbacks.

Write a value into the generic per-resource client-side cache with TTL.

setCachedDatasets

Write the list of datasets into the client-side cache.

setCachedReports

Write the list of reports into the client-side cache.

Write the list of sites into the client-side cache.

setCachedVisualizations

Write the list of visualizations into the client-side cache.

setCachedWorkspaces

Write the list of workspaces into the client-side cache.