Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.auvy.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Search Guide

Search and browse are how most integrations discover content on the unified resource spine: indexed text lives in resource_chunks; POST /v1/search and POST /v1/browse are the primary HTTP surfaces. Paths use plural tokens (assets/, artifacts/, neurons/, …) with an optional pattern after /. AUVY exposes one resource-addressing model across API, SDK, CLI, MCP, and Vault. Set a brain context for brain-scoped resources.

​
Setup

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

const auvy = await fromApiKey(process.env.AUVY_API_KEY!)
For brain-scoped search, configure the client with getBrainId or send X-Brain-Id.

​
Which Surface To Use

NeedUse
List resources by typeauvy.resources.browse.list({ type: 'neurons' })
Keyword, substring, or hybrid type/patternauvy.resources.search.searchSemantic({ query: 'assets/refund', search_mode: 'hybrid' }) (same as deprecated resources.grep.query)
Keyword-only (no vector arm)auvy.resources.search.searchSemantic({ query: 'assets/refund', search_mode: 'lexical' })
Multi-type async searchauvy.resources.search.search({ q, types })
Folder/Vault navigationauvy.resources.browse.resourceTree({ parent_key: '/' })
Owner-scoped RAG retrievalauvy.recollections.search(...)

​
Supported Path Tokens

/v1/search accepts the same primary path tokens: assets, artifacts, stakeholder_maps, meetings, cortex_action_plans, receptors, pathways, neurons, reflexes assets/ is the immutable document lane. artifacts/ is the mutable, versioned document lane. Use Assets and Artifacts for storage details.

​
Browse

Browse is list-only and has no text pattern: 
const rows = await auvy.resources.browse.list({ type: 'artifacts' })

curl -G https://api.auvy.ai/v1/browse \
  --data-urlencode "type=artifacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Brain-Id: YOUR_BRAIN_ID"

​
Hybrid search (/v1/search)

Default search_mode is hybrid: lexical matches on resource_chunks (and catalog heads for synapse kinds) merge with vector hits from the search-resource index when embeddings exist. Use type or type/ to bias listing, and type/pattern to match indexed text. For keyword-only behavior (no vector merge), pass search_mode: 'lexical'. 
const assets = await auvy.resources.search.searchSemantic({
  query: 'assets/refund policy',
})
const neurons = await auvy.resources.search.searchSemantic({
  query: 'neurons/billing escalation agent',
})
Synchronous search uses one type/pattern query. Async multi-facet: 
const { job_id } = await auvy.resources.search.search({
  q: 'renewal risk',
  types: ['meetings', 'stakeholder_maps', 'artifacts', 'neurons'],
  limit: 10,
})

let job = await auvy.jobs.getStatus(job_id)
while (job.status === 'pending' || job.status === 'running') {
  await new Promise((resolve) => setTimeout(resolve, 1000))
  job = await auvy.jobs.getStatus(job_id)
}
Use recollections when you want retrieval within a configured owner context, such as a trace or neuron: 
const hits = await auvy.recollections.search({
  query: 'what did the customer say about renewal timing?',
  owner_type: 'trace',
  owner_ids: ['trace-uuid'],
  strategy: 'hybrid',
  resource_type: 'all',
  limit: 10,
})
resource_type can target asset, artifact, or all.

​
Resource Trees

Vault-style navigation uses the merged resource tree, not text search: 
const root = await auvy.resources.browse.resourceTree({ parent_key: '/' })
const folders = await auvy.resources.browse.resourceTreeBatch({
  parent_keys: ['/Policies', '/Meetings'],
})

​
Best Practices

  1. Use browse or resource-tree for navigation, not text search.
  2. Use POST /v1/search with search_mode: 'lexical' when you want keyword-only type/pattern behavior (default is hybrid, which adds vectors when indexed).
  3. Use search for meaning-based retrieval or multi-facet discovery (GET /v1/search + job_id).
  4. Prefer assets/ and artifacts/ in new queries; memories/ is accepted as an alias and normalizes to assets/ in responses.
  5. Poll async search jobs through auvy.jobs.getStatus with backoff.