Canonical @auvy-os/client reference for agents — version-pinned factories, namespaces, and top methods.

TypeScript SDK source of truth

Canonical reference for agents and integrators using @auvy-os/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-os/client

Authenticate

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

const auvy = await fromApiKey(process.env.AUVY_API_KEY!)
// Validates key via GET /v1/session/context → workspaceId, workspaceSlug

Factory	Use
`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.

Namespace	Purpose
`resources`	Browse, search, and `patchCentral` on the workspace catalog
`resourceStore`	Assets, artifacts, ingest, chunks (`/v1/assets`, `/v1/artifacts`)
`receptors`	Resolve, invoke, shares, `invokeAndStream`, title generation
`receptorChannelBindings`	Slack/Teams/email bindings to receptors
`neurons`	Agent CRUD, invoke, reflex APIs, catalog soft-delete/restore
`pathways`	Graph CRUD, execute, validate, compile
`reflexes`	Tool bundle CRUD
`jobs`	Execute, list, getStatus, cancel, resume, provideInput
`traces`	Threads: get, list, getEngrams, addMessage
`skills`	Brain-scoped markdown skills CRUD
`interventions`	Human-in-the-loop list, get, respond
`public`	Share-token flows for receptors, traces, interventions
`health`	Health check
`config`	Model and embedding configuration
`chat`	Document OCR multipart helpers
`browse`	Catalog list and trees — use `resources.browse`
`search`	Hybrid and lexical search — use `resources.search`

Top methods for agents

Task	Method
Fire a receptor trigger	`auvy.receptors.get(ws, slug)` then `auvy.receptors.fire(receptor.id, { message })`
Fire and stream to done	`auvy.receptors.invokeAndStream(slug, ...)`
Job status	`auvy.jobs.getStatus(jobId)`
Stream job tokens	`createStream(auvy, jobId)` or `streamJobUntilComplete(auvy, jobId, callbacks)`
List catalog	`auvy.resources.browse.list({ … })`
Hybrid search	`auvy.resources.search.searchSemantic({ query, … })`
Read trace messages	`auvy.traces.getEngrams(traceId, { brainId })`
Paginate lists	`for 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-os/client; use @auvy-os/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-os/client'

Errors

import { AUVYError, ERROR_CODES } from '@auvy-os/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.

Introduction — agent onboarding
SDK resources — namespace table with API links
Jobs, streaming, and errors — SSE, errors, reconnect
SDK introduction — AUVY OS vs Connect

TypeScript SDK source of truth

On this page