Skip to main content

​
TypeScript SDK source of truth

Canonical reference for agents and integrators using @auvy-synapse/client. Aligned with npm version 0.6.0 and the public OpenAPI integrator contract.
Are you an AI agent? Prefer this page over guessing method names. Hosted skill: agent-onboarding/SKILL.md.

​
Install

npm install @auvy-synapse/client

​
Authenticate

import { fromApiKey } from '@auvy-synapse/client'

const auvy = await fromApiKey(process.env.AUVY_API_KEY!)
// Validates key via GET /v1/session/context → workspaceId, workspaceSlug
FactoryUse
fromApiKey()Recommended for servers, scripts, agents. Reads AUVY_API_KEY / AUVY_API_URL from env when args omitted.
createAUVYClient({ apiKey, baseUrl, getBrainId, … })Manual config without bootstrap
createAUVYClient({ publishableKey, getAccessToken })Browser apps with JWT
Brain-scoped calls: set getBrainId, AUVY_BRAIN_ID, or per-request brainId in options → sends X-Brain-Id.

​
Resource namespaces

Each key exists as auvy.<key>. Descriptions match AUVY_CLIENT_RESOURCE_SURFACE in the published package.
NamespacePurpose
resourcesBrowse, search, and patchCentral on the workspace catalog
resourceStoreAssets, artifacts, ingest, chunks (/v1/assets, /v1/artifacts)
receptorsResolve, invoke, shares, invokeAndStream, title generation
receptorChannelBindingsSlack/Teams/email bindings to receptors
neuronsAgent CRUD, invoke, reflex APIs, catalog soft-delete/restore
pathwaysGraph CRUD, execute, validate, compile
reflexesTool bundle CRUD
jobsExecute, list, getStatus, cancel, resume, provideInput
tracesThreads: get, list, getEngrams, addMessage
skillsBrain-scoped markdown skills CRUD
interventionsHuman-in-the-loop list, get, respond
publicShare-token flows for receptors, traces, interventions
healthHealth check
configModel and embedding configuration
chatDocument OCR multipart helpers
browseCatalog list and trees — use resources.browse
searchHybrid and lexical search — use resources.search

​
Top methods for agents

TaskMethod
Fire a receptor triggerauvy.receptors.get(ws, slug) then auvy.receptors.fire(receptor.id, { message })
Fire and stream to doneauvy.receptors.invokeAndStream(slug, ...)
Job statusauvy.jobs.getStatus(jobId)
Stream job tokenscreateStream(auvy, jobId) or streamJobUntilComplete(auvy, jobId, callbacks)
List catalogauvy.resources.browse.list({ … })
Hybrid searchauvy.resources.search.searchSemantic({ query, … })
Read trace messagesauvy.traces.getEngrams(traceId, { brainId })
Paginate listsfor await (const row of auvy.receptors.paginate({ pageSize: 20 })) { … }
See Jobs, streaming, and errors for waiter vs poll patterns.

​
Do not use (common mistakes)

  • client.v1.* — escape hatch only when no typed namespace exists
  • client.integrations — not on @auvy-synapse/client; use @auvy-synapse/connect-client
  • Trusting client-supplied workspace_id in your own backend — the SDK sends auth-derived workspace; your server must enforce the same

​
Streaming exports

import {
  createStream,
  streamJobTokens,
  streamJobUntilComplete,
  subscribeJobStream,
  isTokenChunk,
  isCompleteChunk,
  isErrorChunk,
} from '@auvy-synapse/client'

​
Errors

import { AUVYError, ERROR_CODES } from '@auvy-synapse/client'

if (e instanceof AUVYError) {
  if (AUVYError.isRateLimitError(e)) { /* backoff */ }
  if (AUVYError.isRetryableError(e)) { /* retry */ }
  if (AUVYError.isTrialExpiredError(e)) { /* handle quota / plan limits */ }
}
Full catalog: Jobs, streaming, and errors.