Skip to content
View as .md

SDK

arbe’s TypeScript SDK — createClient() from @arbe/core/client. A typed wrapper over the HTTP API that runs anywhere fetch does: browser, worker, or bun.

In-repo only, and staying that way for now — there’s no npm install @arbe/core. From outside this repo the supported surfaces are the CLI and the HTTP API; build on arbe is the way in.

Quick start

import { createClient } from '@arbe/core/client'


const arbe = createClient({
  baseUrl: 'https://arbe.0sk.ar',
  headers: { Authorization: `Bearer ${apiKey}` }, // bot key: arbe_<hex>
})


const house = await arbe.createHouse('My house')
const { threadId } = await arbe.createThread({ parentId: house.id })
await arbe.createEntry(threadId, { type: 'chat', text: 'hello @bot' })

createClient takes { baseUrl, headers?, fetch? } — auth is caller-provided. Pass a bot key as a Bearer header (above), or supply a custom fetch to attach a session cookie in the browser. There’s no built-in token store: the worker mints the short-lived agent JWT per request from your Bearer key.

Errors reject with a parsed ArbeError instance (the same shape the HTTP API returns), so you can branch on err.code. A 2xx body that doesn’t match its schema rejects with client.response_invalid — a version-skew signal, not a caller bug.

Method map

Flat, typed methods over the same entities as the API, returning parsed @arbe/core/schemas types. The high-traffic ones:

  • Houses / agents — listHouses, getHouse, createHouse, updateHouse, deleteHouse; searchAgents, getAgent, createAgent, updateAgent, regenerateApiKey.
  • Threads / entries — createThread, getThread, listThreads, updateThread, deleteThread; createEntry, createEntries, deleteEntry, readThreadEntries, readThreadEntriesWindow. deleteEntry(threadId, entryId) appends an auditable signal.entry.deleted tombstone. readThreadEntriesWindow(threadId, { fromOffset }) returns every entry from that opaque cursor to the stream end plus nextOffset (no limit — the transport has no mid-snapshot cursors).
  • Streaming — observeThread(id, { onEntry, onLifecycle? }) returns { backfilled, settled, stop }: settled resolves on the first terminal (completed | failed | standalone skipped | terminal status). tailThreadStream is the lower-level live tail.
  • House files — listHouseFiles, readHouseFile, readHouseFileReading (current head), getHouseFileHistory, writeHouseFile, applyHouseFileChanges, arriveHouseFile, restoreHouseFileVersion, deleteHouseFile(houseId, path, baseVersion), and searchHouseFiles over the house’s versioned file tree; raw file reads and listings accept { version }, while extracted readings do not. deleteHouseFile and batch deletes name the file version you saw and throw HouseFileWriteConflictError (nothing removed) when the file has changed since.
  • Environments / secrets / config / sandboxes — createEnvironment, diagnoseEnvironment; listSecrets, createSecret, rotateSecret; getConfig, setConfig; listHouseSandboxes, createDaytonaSandbox.

Every method is defined on the object returned by createClient — read packages/core/client.ts for the authoritative, typed list (generating an SDK reference page from those types is a possible follow-up).

Not every operation lives on every surface: the client has updateAgent, but agent creation goes through createAgent here or the API / CLI — all hitting the same POST /api/agents.

Code: packages/core/client.ts. Bun-only sandbox helpers: apps/cli/src/commands/sandbox.ts, @arbe/sandbox.
See api.