Search API
Search across receptors, pathways, neurons, and reflexes using semantic similarity. Two endpoints: POST /v1/search (sync, grep-like format) and GET /v1/search (async job).
POST /v1/search (Sync Semantic)
Semantic similarity search. Returns results immediately in grep-like format. Requires X-Brain-Id.
Request Body
| Field | Type | Required | Description |
|---|
query | string | Yes | type/pattern. Example: neurons/billing help, pathways/invoice workflow |
Supported Types
neurons, pathways, receptors, reflexes. For memories, use Recollections search.
Example
curl -X POST https://api.auvy.ai/v1/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Brain-Id: YOUR_BRAIN_ID" \
-H "Content-Type: application/json" \
-d '{"query": "neurons/billing help"}'
Response
{
"type": "neurons",
"results": [
{ "path": "neurons/uuid", "title": "...", "snippet": "...", "score": 0.89 }
]
}
GET /v1/search (Async)
Search across multiple resource types using semantic similarity (for neurons) and keyword search (for other types).
Brain scope required. Include the X-Brain-Id header or configure getBrainId in the public client.
| Header | Type | Description |
|---|
X-Brain-Id | string (UUID) | Required. Brain ID for scoping |
Query Parameters
| Parameter | Type | Description |
|---|
q | string | Required. Search query |
types | string/array | Resource types to search: receptors, pathways, neurons, reflexes |
type | string | Single resource type (use types for multiple) |
limit | number | Maximum number of results per type |
threshold | number | Similarity threshold (0-1) |
offset | number | Offset for pagination |
visibility | string | Filter by visibility: public or private |
is_active | boolean | Filter by active status |
Example Request
const searchJob = await auvy.search.search({
q: 'completion',
types: ['receptors', 'pathways', 'neurons', 'reflexes'],
limit: 10
})
curl "https://api.auvy.ai/v1/search?q=completion&types=[\"receptors\",\"pathways\",\"neurons\",\"reflexes\"]&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Brain-Id: YOUR_BRAIN_ID"
Example Response
{
"job_id": "job-uuid",
"status": "pending"
}
Search operations are asynchronous. The response includes a job_id that you must poll to get results. See Job Status below. Polling for Results
After receiving a job_id, poll the job status endpoint:
const job = await auvy.jobs.getStatus('job-uuid')
curl https://api.auvy.ai/v1/jobs/job-uuid \
-H "Authorization: Bearer YOUR_API_KEY"
{
"id": "job-uuid",
"status": "completed",
"result": {
"receptors": [...],
"pathways": [...],
"neurons": [...],
"reflexes": [...]
}
}
Memory Search
Search memory chunks by semantic similarity.
Request Body
| Field | Type | Required | Description |
|---|
query | string | Yes | Search query |
recollection_ids | array | No | Filter by recollection IDs |
memory_ids | array | No | Filter by memory IDs |
limit | number | No | Maximum number of results (default: 10) |
threshold | number | No | Similarity threshold (0-1) |
Example Request
const results = await auvy.request<{
chunks: Array<{
id: string
content: string
similarity: number
memory_id: string
metadata: Record<string, unknown>
}>
}>('/v1/search/memories', {
method: 'POST',
body: {
query: 'machine learning',
limit: 10,
threshold: 0.7
}
})
curl -X POST https://api.auvy.ai/v1/search/memories \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "machine learning",
"limit": 10,
"threshold": 0.7
}'
Example Response
{
"chunks": [
{
"id": "chunk-uuid",
"content": "Machine learning is a subset of AI...",
"similarity": 0.95,
"memory_id": "memory-uuid",
"metadata": {}
}
]
}
Job Status
Get the status of an async search job.
Path Parameters
| Parameter | Type | Description |
|---|
job_id | string | Job UUID from search response |
Job Statuses
pending - Job is queuedprocessing - Job is being processedcompleted - Job completed successfullyfailed - Job failed with error
Example Response (Pending)
{
"id": "job-uuid",
"status": "pending",
"created_at": "2024-01-01T00:00:00Z"
}
Example Response (Completed)
{
"id": "job-uuid",
"status": "completed",
"result": {
"receptors": [...],
"pathways": [...],
"neurons": [...],
"reflexes": [...]
},
"created_at": "2024-01-01T00:00:00Z",
"completed_at": "2024-01-01T00:00:05Z"
}
Search Types
Semantic Search (Neurons)
Neurons use semantic similarity search based on embeddings. Results are ranked by similarity score.
Keyword Search (Synapses, Pathways, Reflexes)
Other resource types use keyword search matching against names, descriptions, and metadata.
Best Practices
- Use appropriate types - Specify
types array to search only relevant resource types
- Set similarity threshold - Use
threshold to filter low-quality results
- Poll job status - For async searches, poll job status until completion
- Limit results - Use
limit to control result set size
- Combine with filters - Use
visibility and is_active to narrow results