Developer API — tRPC, REST, and SDK

Every Synap pod exposes a full API for building on top of your data. Three interfaces cover different use cases: tRPC for typed real-time access, Hub Protocol REST for AI agent integration, and the TypeScript SDK for web applications.

Three interfaces, one data layer

Synap does not force you into a single API style. Depending on your integration, you choose the interface that fits best:

• tRPC — The primary interface. Fully typed, real-time subscriptions, batched requests. Used by the Synap desktop app and all first-party clients. Base URL: ${podUrl}/trpc (no /api prefix).
• Hub Protocol REST — A RESTful interface designed for AI agent integration and external services. Bearer token authentication. Used by the intelligence service and third-party automations. Base URL: ${podUrl}/api/hub.
• @synap/sdk — A TypeScript SDK that wraps tRPC with ergonomic helpers. Supports both cookie-based auth (for browser apps on the same domain) and token-based auth (for server-side scripts).

Authentication

API access requires authentication. Two methods are supported:

• Bearer token — For server-to-server and automation use cases. Create an API key in Settings and pass it in the Authorization: Bearer <key> header.
• Session cookie — For browser-based apps running on the same domain. The @synap/sdk handles cookie management automatically when initialized in cookie mode. Better Auth manages sessions on the backend.

API keys are scoped with granular permissions. You can create read-only keys, write-only keys, or keys limited to specific operations. Scopes include entity CRUD, view management, channel access, document operations, search, profile management, and more — 18 permission scopes in total.

Key operations

Entities

Create, read, update, and delete entities. List entities with filters by profile type, property values, date ranges, and workspace scope. Update individual properties without replacing the full entity.

// Create an entity via Hub Protocol REST
POST /api/hub/entities
{
  "userId": "user_abc",
  "workspaceId": "ws_123",
  "type": "task",
  "title": "Review Q3 report",
  "properties": {
    "status": "todo",
    "priority": 2,
    "dueDate": "2026-04-15"
  }
}

Search

Full-text and semantic search across all entities. Pass a query string to get instant results ranked by relevance. Filter by workspace, profile type, or collections.

// Search via Hub Protocol REST
GET /api/hub/search?userId=user_abc&query=quarterly+report&limit=10

Views

Create and manage views programmatically. Define the view type, filters, sorting, and grouping. Useful for generating dashboards or creating views from automation workflows.

Channels

Send messages to channels, read channel history, and create new channels. For AI integration, sending a message to an ai_thread channel triggers the intelligence service and returns the AI response.

Documents

Create and update rich-text documents. Documents support Markdown content and are associated with entities through the entity's documentId field.

Profiles

List available profiles, create custom profiles, and manage property definitions. Profiles define the schema for entity types and are workspace-scoped.

Rate limits

API rate limits depend on your pod tier. Free pods have conservative limits to prevent abuse. Pro and Team tiers have higher limits suitable for automation workloads. Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response so you can implement backoff in your clients.

Using the TypeScript SDK

import { createSynapClient } from '@synap/sdk';

// Token-based auth (server-side)
const client = createSynapClient({
  podUrl: 'https://pod.yourdomain.com',
  apiKey: process.env.SYNAP_API_KEY,
});

// Create an entity
const entity = await client.entities.create({
  workspaceId: 'ws_123',
  type: 'note',
  title: 'Meeting notes — March standup',
});

// Search
const results = await client.search.query({
  query: 'standup notes',
  limit: 5,
});

Related guides