Client SDK
Truss exposes a framework-agnostic REST API that works with any language or HTTP client. Instead of locking you into a proprietary SDK, Truss uses standard fetch (or any HTTP library) with JSON payloads — the same patterns you already know.
Why fetch-based?
Section titled “Why fetch-based?”- Zero dependencies — no SDK package to install, version, or bundle.
- Works everywhere — browsers, Node.js, Deno, Bun, Python, Go, cURL.
- Framework-agnostic — the same API calls work whether you use Next.js, SvelteKit, Remix, or a plain script.
- Migration API — Truss auto-detects 15+ migration frameworks (Prisma, Drizzle, Knex, TypeORM, Sequelize, golang-migrate, Flyway, Liquibase, and more) so you can bring your existing schema tooling.
Base setup
Section titled “Base setup”const TRUSS_URL = 'http://localhost:8787';const TRUSS_KEY = 'truss_pk_your_anon_key'; // or truss_sk_ for service_role
async function truss(path: string, options: RequestInit = {}) { const res = await fetch(`${TRUSS_URL}${path}`, { ...options, headers: { 'apikey': TRUSS_KEY, 'Content-Type': 'application/json', ...options.headers, }, }); if (!res.ok) { const err = await res.json().catch(() => ({ error: res.statusText })); throw new Error(err.error || res.statusText); } return res.json();}You can wrap this helper in a module and import it anywhere in your app. For server-side usage, use a service_role key (truss_sk_). For client-side (browser) usage, use the anon key (truss_pk_).
A browser anon key is read-only (SELECT-only, RLS-enforced) unless the request also carries a verified user JWT in the Authorization: Bearer header, which promotes it to the authenticated role for full DML. See API Keys.
Querying data
Section titled “Querying data”// Select all usersconst users = await truss('/v1/db/users');
// With filters and orderingconst activeUsers = await truss( '/v1/db/users?active=eq.true&order=created_at.desc&limit=10');
// Select specific columnsconst names = await truss('/v1/db/users?select=id,name');
// Filter with INconst specific = await truss('/v1/db/users?id=in.(1,2,3)');Inserting data
Section titled “Inserting data”// Single rowconst [newUser] = await truss('/v1/db/users', { method: 'POST', body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' }),});
// Multiple rowsconst newUsers = await truss('/v1/db/users', { method: 'POST', body: JSON.stringify([ { name: 'Alice', email: 'alice@example.com' }, { name: 'Bob', email: 'bob@example.com' }, ]),});Updating data
Section titled “Updating data”// Update matching rows (filter required)const updated = await truss('/v1/db/users?id=eq.42', { method: 'PATCH', body: JSON.stringify({ name: 'Updated Name' }),});Deleting data
Section titled “Deleting data”// Delete matching rows (filter required)const deleted = await truss('/v1/db/users?id=eq.42', { method: 'DELETE',});Calling functions
Section titled “Calling functions”const result = await truss('/v1/db/rpc/calculate_total', { method: 'POST', body: JSON.stringify({ order_id: 42 }),});Running raw SQL
Section titled “Running raw SQL”Requires a service_role key:
const SERVICE_KEY = 'truss_sk_your_service_key';
const result = await fetch(`${TRUSS_URL}/v1/sql`, { method: 'POST', headers: { 'apikey': SERVICE_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ sql: 'SELECT * FROM users WHERE email ILIKE $1', params: ['%@example.com'], }),});
const { rows, columns, rowCount } = await result.json();Transactions
Section titled “Transactions”const { results } = await fetch(`${TRUSS_URL}/v1/sql/transaction`, { method: 'POST', headers: { 'apikey': SERVICE_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ statements: [ { sql: 'INSERT INTO orders (total) VALUES ($1) RETURNING id', params: [99.99] }, { sql: 'INSERT INTO order_items (order_id, product_id) VALUES ($1, $2)', params: [null, 5] }, ], }),}).then(r => r.json());File uploads
Section titled “File uploads”The presign-upload endpoint lives on the dashboard API (/api/*), which is authenticated by the dashboard session cookie — not an API key. It is not part of the API-key /v1 surface, so this example only works from a browser session that is already signed in to the Truss dashboard (the request must carry the session cookie). It is a dashboard-only flow, not a server-to-server one.
// 1. Get a presigned upload URL (dashboard session required — sends the session cookie)const { url, headers } = await fetch(`${TRUSS_URL}/api/storage/buckets/my-bucket/objects/presign-upload`, { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ key: 'photos/avatar.jpg', contentType: 'image/jpeg' }),}).then(r => r.json());
// 2. Upload directly to S3await fetch(url, { method: 'PUT', headers, body: file, // File object from <input type="file">});Realtime (WebSocket)
Section titled “Realtime (WebSocket)”function connectRealtime(url = 'ws://localhost:8787/realtime') { const ws = new WebSocket(url);
ws.onmessage = (event) => { const data = JSON.parse(event.data); console.log(`${data.operation} on ${data.table}:`, data.row); };
ws.onclose = () => { // Auto-reconnect after 2 seconds setTimeout(() => connectRealtime(url), 2000); };
return ws;}
const ws = connectRealtime();Using with popular frameworks
Section titled “Using with popular frameworks”The fetch-based pattern works identically across frameworks. Here are quick examples:
Next.js (App Router)
Section titled “Next.js (App Router)”export async function GET() { const users = await truss('/v1/db/users?limit=50'); return Response.json(users);}SvelteKit
Section titled “SvelteKit”export async function load() { const users = await truss('/v1/db/users'); return { users };}Plain Node.js / Bun / Deno
Section titled “Plain Node.js / Bun / Deno”const users = await truss('/v1/db/users');console.log(users);Python
Section titled “Python”import requests
TRUSS_URL = "http://localhost:8787"TRUSS_KEY = "truss_pk_your_anon_key"
headers = {"apikey": TRUSS_KEY, "Content-Type": "application/json"}users = requests.get(f"{TRUSS_URL}/v1/db/users", headers=headers).json()curl -H "apikey: truss_pk_your_anon_key" \ http://localhost:8787/v1/db/usersPlatform status
Section titled “Platform status”const status = await fetch(`${TRUSS_URL}/v1/status`, { headers: { 'apikey': SERVICE_KEY },}).then(r => r.json());
console.log(`Database: ${status.database.size_gb} GB`);console.log(`Tables: ${status.database.table_count}`);console.log(`Schemas: ${status.database.schema_count}`);console.log(`Projects: ${status.resources.projects.total}`);console.log(`Active API keys: ${status.resources.api_keys.active}`);console.log(`Active branches: ${status.resources.branches.active}`);console.log(`Storage configured: ${status.integrations.storage.configured}`);console.log(`Auth configured: ${status.integrations.auth.configured}`);The response groups data under platform, database (size_bytes, size_gb, table_count, schema_count), plan, resources (projects, api_keys, branches, backups, webhooks, realtime_subscriptions), and integrations (auth, authz, oauth2, gateway, storage, cache — each with a configured flag). /v1/status requires a service_role key.
Error handling
Section titled “Error handling”try { const users = await truss('/v1/db/nonexistent_table');} catch (err) { // Error messages come from the API: // "relation \"nonexistent_table\" does not exist" console.error(err.message);}The API returns structured errors with error, code (Postgres error code), detail, and hint fields when available.