API Reference

Auto-generated from tRPC router definitions. Do not edit manually — run pnpm gen-docs in synap-backend/packages/api to regenerate.

This page lists every tRPC procedure exposed by the Synap data pod. All procedures are callable via @synap/sdk (vanilla JS) or @synap/react hooks.

How to read this page

query — use .useQuery(input) (React) or .query(input) (vanilla)
mutation — use .useMutation() (React) or .mutate(input) (vanilla)
Router key — the first segment in the call chain, e.g. entities.list

// Vanilla JS
import { createSynapClient } from "@synap/sdk";
const synap = createSynapClient({ podUrl, apiKey, workspaceId });
const result = await synap.entities.list.query({ limit: 20 });
 
// React
import { useSynap } from "@synap/react";
const { data } = useSynap().entities.list.useQuery({ limit: 20 });

Agent Configs

Router key: agentConfigs

`agentConfigs.list` (query)

List all agent configs for the current user in this workspace.

API Keys

Router key: apiKeys

`apiKeys.listSystemKeys` (query)

List all system keys (System Admin only)

List all available capabilities. Returns core features, plugins, and intelligence services with cached health status (lastHealthCheck). Does NOT ping services — use checkHealth for that so this query stays fast.

Channel Gateway

Router key: channelGateway

`channelGateway.list` (query)

List all channel connections for the current user.

Connectors

Router key: connectors

`connectors.status` (query)

Diagnostic: returns what the pod sees for CP connection settings. Helps debug provisioning issues.

Files

Router key: files

`files.listBuckets` (query)

List buckets

Health

Router key: health

`health.alive` (query)

Liveness probe - basic "is the service running" check Should always return quickly, used by orchestrators

`health.ready` (query)

Readiness probe - is the service ready to handle traffic Checks all critical dependencies

`health.migrations` (query)

Migration status - shows applied database migrations

`health.metrics` (query)

System metrics - basic operational metrics

Inbox

Router key: inbox

`inbox.stats` (query)

Get stats (for header display)

Intelligence (AI)

Router key: intelligence

`intelligence.listSpecialisations` (query)

List specialisations from the connected intelligence service. Proxies to hub GET /api/specialisations — gracefully returns [] if the hub is unreachable (service not yet connected). Used by the branch picker and Intelligence Studio Capabilities tab.

`intelligence.agentDefinitions` (query)

List agent definitions from the connected intelligence service. Proxies to hub GET /api/agent-definitions — gracefully returns [] if the hub is unreachable (service not yet connected).

`intelligence.getServiceCommands` (query)

getServiceCommands Returns previously stored Docker run commands for provisioned services. Allows wizards to show the command on re-open without regenerating credentials.

`intelligence.getLatestMemoryState` (query)

getLatestMemoryState Returns the latest compacted memory state for the user's personal AI timeline. Compacted states are written by any Hub Protocol service that implements the session-scoped memory protocol (currently Synap Agent Hub). Returns null if no state has been produced yet (new user or legacy service).

`intelligence.getServiceManifest` (query)

getServiceManifest Returns the AgentManifest for the workspace's active IS. For Synap IS (default): always fetches live from IS. For custom IS: returns cached manifest from DB metadata, refreshes if stale (>1h).

`intelligence.listSystemSkills` (query)

listSystemSkills Returns the list of system skills served by the active IS.

`intelligence.listRegisteredServices` (query)

listRegisteredServices Returns all IS records registered for the workspace. apiKey is never returned.

MCP Servers

Router key: mcpServers

`mcpServers.list` (query)

List all MCP servers for the current workspace.

Notifications

Router key: notifCenter

`notifCenter.unreadCount` (query)

Total unread count for the bell badge.

`notifCenter.markAllRead` (mutation)

Mark all unread notifications as read.

`notifCenter.dismissAll` (mutation)

Dismiss all notifications (clear bell).

`notifCenter.getPrefs` (query)

Get notification preferences for the current user + workspace.

Preferences

Router key: preferences

`preferences.get` (query)

Get user preferences

`preferences.getViewModes` (query)

Get view mode preferences

`preferences.getIntelligenceServices` (query)

Get intelligence service preferences and available services

Profile Relations

Router key: profileRelations

`profileRelations.list` (query)

List all profile relations for profiles accessible in this workspace. Used by the data structure viewer.

Profiles

Router key: profiles

`profiles.list` (query)

List accessible profiles (system + workspace + user)

Property Definitions

Router key: propertyDefs

`propertyDefs.list` (query)

List property definitions accessible to the calling workspace. Returns only defs whose profile is accessible to this workspace (system profiles, workspace-owned profiles, shared profiles with access, user profiles) plus globally-scoped defs (profileId IS NULL). Uses workspaceProcedure so ctx.workspaceId is available.

Relation Definitions

Router key: relationDefs

`relationDefs.list` (query)

List all relation definitions for the current workspace

Relations

Router key: relations

`relations.listTypes` (query)

List all available relation types with metadata Returns all relation definitions from the workspace's relation_defs table. Default types (assigned_to, depends_on, etc.) are seeded during workspace creation.

Vault

Router key: secretsVault

`secretsVault.hasVault` (query)

Check if vault is set up for current user

`secretsVault.getVaultMetadata` (query)

Get vault metadata (for client-side password verification)

`secretsVault.recordUnlock` (mutation)

Record vault unlock (for audit trail)

`secretsVault.generateRecoveryKey` (mutation)

Generate recovery key (server-side for security)

`secretsVault.getCategories` (query)

Get all categories

`secretsVault.getTags` (query)

Get all tags

`secretsVault.sharedWithMe` (query)

Get secrets shared with me

`secretsVault.getSecurityStats` (query)

Get security stats (compromised, weak passwords, old passwords)

Workspace Setup

Router key: setup

`setup.status` (query)

System

Router key: system

`system.getCapabilities` (query)

Get system capabilities Returns all registered event types, handlers, tools, and routers. This gives a complete overview of the system's architecture.

`system.getDashboardMetrics` (query)

Get Dashboard Metrics (V2) Returns aggregated real-time metrics optimized for the Dashboard view. Includes health status, throughput, latency, and key system statistics.

`system.getServiceHealth` (query)

Get service health status Checks the connectivity and health of all dependent services: - Postgres (Database) - Typesense (Search) - MinIO (Storage) - Hydra (OAuth Provider) - Kratos (Identity Provider)