Utilities
Shared utilities — query-key factories, cache-invalidation helper, and the generic `useSdkQuery` / `useSdkMutation` escape hatches.
Hooks
agentKeys composite
Query key factory for agents.
agentKeys = {
all: () => ["agents"] as const,
list: (params?: any) => ["agents", "list", params] as const,
detail: (id: string) => ["agents", id] as const,
};agentVersionKeys composite
Query key factory for agent-versions.
agentVersionKeys = { all: () => ["agent-versions"] as const, list: (params?: any) => ["agent-versions", "list", params] as const, detail: (id: string) => ["agent-versions", id]...apiKeyKeys composite
Query key factory for api-keys.
apiKeyKeys = {
all: () => ["api-keys"] as const,
list: (params?: any) => ["api-keys", "list", params] as const,
detail: (id: string) => ["api-keys", id] as const,
};apiKeyKeys composite
Query key factory for API keys.
apiKeyKeys = {
all: () => ["api-keys"] as const,
list: (params?: any) => ["api-keys", "list", params] as const,
detail: (id: string) => ["api-keys", id] as const,
};apiKeys_ composite
Query key factory for apis.
apiKeys_ = {
all: () => ["apis"] as const,
list: (params?: any) => ["apis", "list", params] as const,
detail: (id: string) => ["apis", id] as const,
};appDomainKeys composite
Query key factory for app-domains.
appDomainKeys = {
all: () => ["app-domains"] as const,
list: (params?: any) => ["app-domains", "list", params] as const,
detail: (id: string) => ["app-domains", id] as const,
};appKeys composite
Query key factory for apps.
appKeys = {
all: () => ["apps"] as const,
list: (params?: any) => ["apps", "list", params] as const,
detail: (id: string) => ["apps", id] as const,
};appKeys composite
appKeys = { ..._appKeysGen, files: (id: string, path?: string) => ["apps", id, "files", path] as const, fileContent: (id: string, path: string) => ["apps", id, "file",...appVersionKeys composite
Query key factory for app-versions.
appVersionKeys = { all: () => ["app-versions"] as const, list: (params?: any) => ["app-versions", "list", params] as const, detail: (id: string) => ["app-versions", id] as co...buildKeys composite
Query key factory for builds.
buildKeys = {
all: () => ["builds"] as const,
list: (params?: any) => ["builds", "list", params] as const,
detail: (id: string) => ["builds", id] as const,
};buildKeys composite
Query key factory for builds.
buildKeys = {
all: () => ["builds"] as const,
list: (params?: any) => ["builds", "list", params] as const,
detail: (id: string) => ["builds", id] as const,
};cleanParams composite
Strip undefined and null values from a params object before passing
to URLSearchParams (which would otherwise stringify them as "undefined" / "null").
cleanParams(params?: Record<string, unknown>): Record<string, string>cleanupTaskKeys composite
Query key factory for cleanup-tasks.
cleanupTaskKeys = { all: () => ["cleanup-tasks"] as const, list: (params?: any) => ["cleanup-tasks", "list", params] as const, detail: (id: string) => ["cleanup-tasks", id] as...cleanupTaskKeys composite
cleanupTaskKeys = {
..._ctKeysGen,
tree: (id: string) => ["cleanup-tasks", id, "tree"] as const,
};connectorKeys composite
Query key factory for connectors.
connectorKeys = {
all: () => ["connectors"] as const,
list: (params?: any) => ["connectors", "list", params] as const,
detail: (id: string) => ["connectors", id] as const,
};databaseKeys composite
Query key factory for databases.
databaseKeys = {
all: () => ["databases"] as const,
list: (params?: any) => ["databases", "list", params] as const,
detail: (id: string) => ["databases", id] as const,
};databaseKeys composite
databaseKeys = { ..._databaseKeysGen, tables: (id: string) => ["databases", id, "tables"] as const, tableDetail: (id: string, tableName: string) => ["databases", id, "table...deployKeys composite
Query key factory for deploys.
deployKeys = {
all: () => ["deploys"] as const,
list: (params?: any) => ["deploys", "list", params] as const,
detail: (id: string) => ["deploys", id] as const,
};deployKeys composite
Query key factory for deploys.
deployKeys = {
all: () => ["deploys"] as const,
list: (params?: any) => ["deploys", "list", params] as const,
detail: (id: string) => ["deploys", id] as const,
};directoryKeys composite
Query key factory for directories.
directoryKeys = {
all: () => ["directories"] as const,
list: (params?: any) => ["directories", "list", params] as const,
detail: (id: string) => ["directories", id] as const,
};elementKeys composite
Query key factory for elements.
elementKeys = {
all: () => ["elements"] as const,
list: (params?: any) => ["elements", "list", params] as const,
detail: (id: string) => ["elements", id] as const,
};elementKeys composite
Query key factory for elements.
elementKeys = {
all: () => ["elements"] as const,
list: (params?: any) => ["elements", "list", params] as const,
detail: (id: string) => ["elements", id] as const,
};elementVersionKeys composite
Query key factory for element-versions.
elementVersionKeys = { all: () => ["element-versions"] as const, list: (params?: any) => ["element-versions", "list", params] as const, detail: (id: string) => ["element-versions...emailKeys composite
Query key factory for emails.
emailKeys = {
all: () => ["emails"] as const,
list: (params?: any) => ["emails", "list", params] as const,
detail: (id: string) => ["emails", id] as const,
};endpointKeys composite
Query key factory for endpoints.
endpointKeys = {
all: () => ["endpoints"] as const,
list: (params?: any) => ["endpoints", "list", params] as const,
detail: (id: string) => ["endpoints", id] as const,
};ENTITY_TYPE_TO_QUERY_KEY composite
Maps EntityType (camelCase, from detectEntityType) to QUERY_KEYS entries. Used by useEventStream for automatic cache invalidation.
ENTITY_TYPE_TO_QUERY_KEY = { user: QUERY_KEYS.users, workspace: QUERY_KEYS.workspaces, workspaceMember: QUERY_KEYS["workspace-members"], organization: QUERY_KEYS.organizations, organiz...eventKeys composite
Query key factory for events.
eventKeys = {
all: () => ["events"] as const,
list: (params?: any) => ["events", "list", params] as const,
detail: (id: string) => ["events", id] as const,
};fileKeys composite
Query key factory for files.
fileKeys = {
all: () => ["files"] as const,
list: (params?: any) => ["files", "list", params] as const,
detail: (id: string) => ["files", id] as const,
};functionFileKeys composite
Query key factory for function-files.
functionFileKeys = { all: () => ["function-files"] as const, list: (params?: any) => ["function-files", "list", params] as const, detail: (id: string) => ["function-files", id]...functionKeys composite
Query key factory for functions.
functionKeys = {
all: () => ["functions"] as const,
list: (params?: any) => ["functions", "list", params] as const,
detail: (id: string) => ["functions", id] as const,
};functionVersionKeys composite
Query key factory for function-versions.
functionVersionKeys = { all: () => ["function-versions"] as const, list: (params?: any) => ["function-versions", "list", params] as const, detail: (id: string) => ["function-versi...graphDefinitionKeys composite
Query key factory for graph-definitions.
graphDefinitionKeys = { all: () => ["graph-definitions"] as const, list: (params?: any) => ["graph-definitions", "list", params] as const, detail: (id: string) => ["graph-definiti...graphDefinitionKeys composite
graphDefinitionKeys = {
..._graphDefinitionKeysGen,
graphs: (id: string, params?: any) =>
["graph-definitions", id, "graphs", params] as const,
};graphEdgeKeys composite
Query key factory for graph-edges.
graphEdgeKeys = {
all: () => ["graph-edges"] as const,
list: (params?: any) => ["graph-edges", "list", params] as const,
detail: (id: string) => ["graph-edges", id] as const,
};graphKeys composite
Query key factory for graphs.
graphKeys = {
all: () => ["graphs"] as const,
list: (params?: any) => ["graphs", "list", params] as const,
detail: (id: string) => ["graphs", id] as const,
};graphKeys composite
graphKeys = {
..._graphKeysGen,
data: (id: string) => ["graphs", id, "data"] as const,
};graphNodeKeys composite
Query key factory for graph-nodes.
graphNodeKeys = {
all: () => ["graph-nodes"] as const,
list: (params?: any) => ["graph-nodes", "list", params] as const,
detail: (id: string) => ["graph-nodes", id] as const,
};imageKeys composite
Query key factory for images.
imageKeys = {
all: () => ["images"] as const,
list: (params?: any) => ["images", "list", params] as const,
detail: (id: string) => ["images", id] as const,
};integrationInstallKeys composite
Query key factory for integration-installs.
integrationInstallKeys = { all: () => ["integration-installs"] as const, list: (params?: any) => ["integration-installs", "list", params] as const, detail: (id: string) => ["integrat...integrationKeys composite
Query key factory for integrations.
integrationKeys = { all: () => ["integrations"] as const, list: (params?: any) => ["integrations", "list", params] as const, detail: (id: string) => ["integrations", id] as co...integrationVersionKeys composite
Query key factory for integration-versions.
integrationVersionKeys = { all: () => ["integration-versions"] as const, list: (params?: any) => ["integration-versions", "list", params] as const, detail: (id: string) => ["integrat...logKeys composite
Query key factory for logs.
logKeys = {
all: () => ["logs"] as const,
list: (params?: any) => ["logs", "list", params] as const,
detail: (id: string) => ["logs", id] as const,
};mcpServerKeys composite
Query key factory for mcp-servers.
mcpServerKeys = {
all: () => ["mcp-servers"] as const,
list: (params?: any) => ["mcp-servers", "list", params] as const,
detail: (id: string) => ["mcp-servers", id] as const,
};messageKeys composite
Query key factory for messages.
messageKeys = {
all: () => ["messages"] as const,
list: (params?: any) => ["messages", "list", params] as const,
detail: (id: string) => ["messages", id] as const,
};notificationKeys composite
notificationKeys = {
..._notifKeysGen,
unreadCount: () => ["notifications", "unread-count"] as const,
};notificationKeys composite
Query key factory for notifications.
notificationKeys = { all: () => ["notifications"] as const, list: (params?: any) => ["notifications", "list", params] as const, detail: (id: string) => ["notifications", id] as...oauthApplicationKeys composite
Query key factory for oauth-applications.
oauthApplicationKeys = { all: () => ["oauth-applications"] as const, list: (params?: any) => ["oauth-applications", "list", params] as const, detail: (id: string) => ["oauth-applic...OBSERVATIONAL_EVENT_TYPES composite
Observational event types — events that fire for audit, metrics, or internal signalling and should NOT drive cache invalidation in the React client. Invalidating on these events creates feedback loops where a query triggered from the UI fires an event that invalidates the same query, causing it to refetch, emit again, etc.
Rule: any event where "the set of entity rows" doesn't change goes here. Lifecycle internals (provision_requested / provision_failed), failure-reporting events, loop-prevention events (trigger.fired, workflow.executed — already filtered server-side), and high-volume audit events (database.query_executed) all qualify.
Note: this list is a safety net, NOT the trigger-source allowlist. Events here can still be used as trigger sources by the workflow dispatcher; we're only saying the React client shouldn't refetch caches when they arrive. See apps/run/src/lib/event-catalog.ts for the assistant-side tier classification.
OBSERVATIONAL_EVENT_TYPES = new Set([ // High-volume audit — triggered by every SQL call through executeSql. // Invalidating databaseKeys on each of these creates a runaway loop // when...organizationKeys composite
organizationKeys = {
..._orgKeysGen,
byHandle: (handle: string) => ["organizations", "by-handle", handle] as const,
};organizationKeys composite
Query key factory for organizations.
organizationKeys = { all: () => ["organizations"] as const, list: (params?: any) => ["organizations", "list", params] as const, detail: (id: string) => ["organizations", id] as...organizationMemberKeys composite
Query key factory for organization-members.
organizationMemberKeys = { all: () => ["organization-members"] as const, list: (params?: any) => ["organization-members", "list", params] as const, detail: (id: string) => ["organiza...pageKeys composite
pageKeys = {
..._pageKeysGen,
resolve: (params?: any) => ["pages", "resolve", params] as const,
tree: (workspaceId: string) => ["pages", "tree", workspaceId] as const,
};pageKeys composite
Query key factory for pages.
pageKeys = {
all: () => ["pages"] as const,
list: (params?: any) => ["pages", "list", params] as const,
detail: (id: string) => ["pages", id] as const,
};permissionKeys composite
permissionKeys = { ..._permKeysGen, /** Effective tier of the caller on a (entityType, entityId) pair. */ effectiveTier: (entityType: string, entityId: string) => ["permissio...permissionKeys composite
Query key factory for permissions.
permissionKeys = {
all: () => ["permissions"] as const,
list: (params?: any) => ["permissions", "list", params] as const,
detail: (id: string) => ["permissions", id] as const,
};QUERY_KEYS composite
Flat map of entity name → all() key, for event stream invalidation.
QUERY_KEYS = { agents: agentKeys.all(), "agent-versions": agentVersionKeys.all(), "function-versions": functionVersionKeys.all(), "function-files": functionFileKeys.all()...runKeys composite
Query key factory for runs.
runKeys = {
all: () => ["runs"] as const,
list: (params?: any) => ["runs", "list", params] as const,
detail: (id: string) => ["runs", id] as const,
};scheduleKeys composite
Query key factory for schedules.
scheduleKeys = {
all: () => ["schedules"] as const,
list: (params?: any) => ["schedules", "list", params] as const,
detail: (id: string) => ["schedules", id] as const,
};schemaKeys composite
schemaKeys = {
..._schemaKeysGen,
fields: (id: string, params?: any) =>
["schemas", id, "fields", params] as const,
};schemaKeys composite
Query key factory for schemas.
schemaKeys = {
all: () => ["schemas"] as const,
list: (params?: any) => ["schemas", "list", params] as const,
detail: (id: string) => ["schemas", id] as const,
};secretKeys composite
Query key factory for secrets.
secretKeys = {
all: () => ["secrets"] as const,
list: (params?: any) => ["secrets", "list", params] as const,
detail: (id: string) => ["secrets", id] as const,
};skillKeys composite
Query key factory for skills.
skillKeys = {
all: () => ["skills"] as const,
list: (params?: any) => ["skills", "list", params] as const,
detail: (id: string) => ["skills", id] as const,
};solutionKeys composite
Query key factory for solutions.
solutionKeys = {
all: () => ["solutions"] as const,
list: (params?: any) => ["solutions", "list", params] as const,
detail: (id: string) => ["solutions", id] as const,
};solutionMemberKeys composite
Query key factory for solution-members.
solutionMemberKeys = { all: () => ["solution-members"] as const, list: (params?: any) => ["solution-members", "list", params] as const, detail: (id: string) => ["solution-members...specKeys composite
Query key factory for specs.
specKeys = {
all: () => ["specs"] as const,
list: (params?: any) => ["specs", "list", params] as const,
detail: (id: string) => ["specs", id] as const,
};specMemberKeys composite
Query key factory for spec-members.
specMemberKeys = { all: () => ["spec-members"] as const, list: (params?: any) => ["spec-members", "list", params] as const, detail: (id: string) => ["spec-members", id] as co...swarmEdgeKeys composite
Query key factory for swarm-edges.
swarmEdgeKeys = {
all: () => ["swarm-edges"] as const,
list: (params?: any) => ["swarm-edges", "list", params] as const,
detail: (id: string) => ["swarm-edges", id] as const,
};swarmKeys composite
Query key factory for swarms.
swarmKeys = {
all: () => ["swarms"] as const,
list: (params?: any) => ["swarms", "list", params] as const,
detail: (id: string) => ["swarms", id] as const,
};swarmNodeKeys composite
Query key factory for swarm-nodes.
swarmNodeKeys = {
all: () => ["swarm-nodes"] as const,
list: (params?: any) => ["swarm-nodes", "list", params] as const,
detail: (id: string) => ["swarm-nodes", id] as const,
};swarmVersionKeys composite
Query key factory for swarm-versions.
swarmVersionKeys = { all: () => ["swarm-versions"] as const, list: (params?: any) => ["swarm-versions", "list", params] as const, detail: (id: string) => ["swarm-versions", id]...teamKeys composite
Query key factory for teams.
teamKeys = {
all: () => ["teams"] as const,
list: (params?: any) => ["teams", "list", params] as const,
detail: (id: string) => ["teams", id] as const,
};teamMemberKeys composite
Query key factory for team-members.
teamMemberKeys = { all: () => ["team-members"] as const, list: (params?: any) => ["team-members", "list", params] as const, detail: (id: string) => ["team-members", id] as co...threadKeys composite
threadKeys = {
..._threadKeysGen,
messages: (id: string, params?: any) =>
["threads", id, "messages", params] as const,
};threadKeys composite
Query key factory for threads.
threadKeys = {
all: () => ["threads"] as const,
list: (params?: any) => ["threads", "list", params] as const,
detail: (id: string) => ["threads", id] as const,
};threadParticipantKeys composite
Query key factory for thread-participants.
threadParticipantKeys = { all: () => ["thread-participants"] as const, list: (params?: any) => ["thread-participants", "list", params] as const, detail: (id: string) => ["thread-par...tokenKeys composite
Query key factory for tokens.
tokenKeys = {
all: () => ["tokens"] as const,
list: (params?: any) => ["tokens", "list", params] as const,
detail: (id: string) => ["tokens", id] as const,
};toolKeys composite
Query key factory for tools.
toolKeys = {
all: () => ["tools"] as const,
list: (params?: any) => ["tools", "list", params] as const,
detail: (id: string) => ["tools", id] as const,
};trashKeys composite
Query key factory for trash.
trashKeys = {
all: () => ["trash"] as const,
list: (params?: any) => ["trash", "list", params] as const,
detail: (id: string) => ["trash", id] as const,
};triggerKeys composite
Query key factory for triggers.
triggerKeys = {
all: () => ["triggers"] as const,
list: (params?: any) => ["triggers", "list", params] as const,
detail: (id: string) => ["triggers", id] as const,
};useCreateApiKey mutation
Create a new API key — returns the plaintext value once.
useCreateApiKey(options?: MutationOpts<ApiKeyCreated, CreateApiKeyParams>)Types: ApiKeyCreated · CreateApiKeyParams
useDeleteApiKey mutation
Soft-delete an API key.
useDeleteApiKey(options?: MutationOpts<SuccessResponse, string>)Types: SuccessResponse
useInvalidate composite
Invalidate queries by key. Wraps useQueryClient so consumers
don't need to import @tanstack/react-query directly.
useInvalidate();const invalidate = useInvalidate();
invalidate(agentKeys.all(), functionKeys.all());useListApiKeys query
List API keys.
useListApiKeys(params?: Omit<ListApiKeysParams, | > & { filter?: ApiKeyFilter; orderBy?: ApiKeyOrderBy[]; } & ApiKeyShorthands, options?: QueryOpts<Page<ApiKey>>)Types: ListApiKeysParams · ApiKeyFilter · ApiKeyOrderBy · ApiKeyShorthands · Page · ApiKey
usePurgeApiKey composite
Permanently delete a soft-deleted API key.
usePurgeApiKey(options?: MutationOpts<SuccessResponse, PurgeApiKeyParams>)Types: SuccessResponse · PurgeApiKeyParams
useRestoreApiKey composite
Restore a soft-deleted API key.
useRestoreApiKey(options?: MutationOpts<ApiKey, string>)Types: ApiKey
useRetrieveApiKey query
Get a single API key by ID.
useRetrieveApiKey(id: string, options?: QueryOpts<ApiKey>)Types: ApiKey
userKeys composite
Query key factory for users (admin).
userKeys = { all: () => ["users"] as const, list: (params?: any) => ["users", "list", params] as const, detail: (id: string) => ["users", id] as const, me: () => ["user...useSdkMutation composite
Generic SDK mutation hook for endpoints not covered by specific hooks.
useSdkMutation<TData = unknown, TVars = void>(fn: (vars: TVars) => Promise<TData>, options?: MutationOpts<TData, TVars>)useSdkQuery composite
Generic SDK query hook for endpoints not covered by specific hooks.
useSdkQuery<TData = unknown>(key: string[], fn: () => Promise<TData>, options?: QueryOpts<TData>)useUpdateApiKey mutation
Update an API key's metadata.
useUpdateApiKey(options?: MutationOpts<ApiKey, UpdateApiKeyParams>)Types: ApiKey · UpdateApiKeyParams
videoKeys composite
Query key factory for videos.
videoKeys = {
all: () => ["videos"] as const,
list: (params?: any) => ["videos", "list", params] as const,
detail: (id: string) => ["videos", id] as const,
};webhookCallKeys composite
Query key factory for webhook-calls.
webhookCallKeys = { all: () => ["webhook-calls"] as const, list: (params?: any) => ["webhook-calls", "list", params] as const, detail: (id: string) => ["webhook-calls", id] as...webhookDeliveryAttemptKeys composite
Query key factory for webhook-delivery-attempts.
webhookDeliveryAttemptKeys = { all: () => ["webhook-delivery-attempts"] as const, list: (params?: any) => ["webhook-delivery-attempts", "list", params] as const, detail: (id: string) => ...webhookDeliveryKeys composite
webhookDeliveryKeys = {
..._wdKeysGen,
attempts: (id: string) => ["webhook-deliveries", id, "attempts"] as const,
};webhookDeliveryKeys composite
Query key factory for webhook-deliveries.
webhookDeliveryKeys = { all: () => ["webhook-deliveries"] as const, list: (params?: any) => ["webhook-deliveries", "list", params] as const, detail: (id: string) => ["webhook-deli...webhookEndpointKeys composite
Query key factory for webhook-endpoints.
webhookEndpointKeys = { all: () => ["webhook-endpoints"] as const, list: (params?: any) => ["webhook-endpoints", "list", params] as const, detail: (id: string) => ["webhook-endpoi...webhookSubscriptionKeys composite
Query key factory for webhook-subscriptions.
webhookSubscriptionKeys = { all: () => ["webhook-subscriptions"] as const, list: (params?: any) => ["webhook-subscriptions", "list", params] as const, detail: (id: string) => ["webhoo...withOptimisticUpdate composite
Build optimistic cache update callbacks for detail entity update mutations.
On mutate: cancels in-flight queries for the detail key, snapshots the previous data, and merges the mutation variables into the cached detail entry. On error: rolls back to the snapshot. On settled: invalidates the "all" key so lists refetch.
withOptimisticUpdate(qc: QueryClient, detailKey: (id: string) => readonly unknown[], allKey: () => readonly unknown[], getId: (vars: any) => string)workflowEdgeKeys composite
Query key factory for workflow-edges.
workflowEdgeKeys = { all: () => ["workflow-edges"] as const, list: (params?: any) => ["workflow-edges", "list", params] as const, detail: (id: string) => ["workflow-edges", id]...workflowKeys composite
workflowKeys = {
..._workflowKeysGen,
run: (workflowId: string, runId: string) =>
["workflows", workflowId, "runs", runId] as const,
};workflowKeys composite
Query key factory for workflows.
workflowKeys = {
all: () => ["workflows"] as const,
list: (params?: any) => ["workflows", "list", params] as const,
detail: (id: string) => ["workflows", id] as const,
};workflowNodeKeys composite
Query key factory for workflow-nodes.
workflowNodeKeys = { all: () => ["workflow-nodes"] as const, list: (params?: any) => ["workflow-nodes", "list", params] as const, detail: (id: string) => ["workflow-nodes", id]...workspaceKeys composite
workspaceKeys = { ..._workspaceKeysGen, byHandle: (orgHandle: string, wsHandle: string) => ["workspaces", "by-handle", orgHandle, wsHandle] as const, email: (id: string) => ...workspaceKeys composite
Query key factory for workspaces.
workspaceKeys = {
all: () => ["workspaces"] as const,
list: (params?: any) => ["workspaces", "list", params] as const,
detail: (id: string) => ["workspaces", id] as const,
};workspaceMemberKeys composite
Query key factory for workspace-members.
workspaceMemberKeys = { all: () => ["workspace-members"] as const, list: (params?: any) => ["workspace-members", "list", params] as const, detail: (id: string) => ["workspace-memb...