Search

POST

/v1/search

Perform semantic search across your memories. Returns the most relevant content based on meaning, not just keyword matching.

Request Body

Parameter	Type	Required	Description
`query`	string	Yes	Search query (semantic understanding)
`limit`	number	No	Max results to return (default: 10, max: 100)
`offset`	number	No	Pagination offset (default: 0)
`threshold`	number	No	Minimum relevance score (0-1, default: 0.5)
`spaceId`	string	No	Limit search to specific space
`tags`	string[]	No	Filter by tags
`after`	string	No	Filter by date (ISO 8601)
`before`	string	No	Filter by date (ISO 8601)
`hybrid`	boolean	No	Use hybrid search (semantic + keyword)

Examples

Basic Search

curl -X POST https://api.hypersave.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning best practices",
    "limit": 5
  }'

Search with Filters

curl -X POST https://api.hypersave.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "product launch",
    "tags": ["marketing", "product"],
    "after": "2024-01-01",
    "limit": 10
  }'

Hybrid Search

Combine semantic understanding with keyword matching for best results:

curl -X POST https://api.hypersave.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "TypeScript React hooks tutorial",
    "hybrid": true,
    "limit": 10
  }'

Hybrid search works best when you need both conceptual relevance and specific keyword matches.

High Precision Search

Use a higher threshold to get only highly relevant results:

curl -X POST https://api.hypersave.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue report",
    "threshold": 0.8,
    "limit": 5
  }'

Response

{
  "success": true,
  "results": [
    {
      "id": "doc_abc123",
      "content": "Best practices for machine learning model training include...",
      "title": "ML Training Guide",
      "score": 0.94,
      "tags": ["machine-learning", "tutorial"],
      "createdAt": "2024-01-10T14:30:00Z",
      "metadata": {
        "author": "data-team"
      }
    },
    {
      "id": "doc_xyz789",
      "content": "When deploying machine learning models to production...",
      "title": "ML Deployment Checklist",
      "score": 0.87,
      "tags": ["machine-learning", "devops"],
      "createdAt": "2024-01-08T09:15:00Z"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}

Response Fields

Field	Type	Description
`results`	array	Array of matching memories
`results[].id`	string	Memory document ID
`results[].content`	string	Memory content
`results[].title`	string	Memory title
`results[].score`	number	Relevance score (0-1)
`results[].tags`	string[]	Associated tags
`results[].createdAt`	string	Creation timestamp
`results[].metadata`	object	Custom metadata
`pagination`	object	Pagination info

Semantic vs Keyword Search

Aspect	Semantic Search	Keyword Search	Hybrid
"car maintenance" finds "vehicle repair"	✅	❌	✅
Exact phrase matching	❌	✅	✅
Conceptual understanding	✅	❌	✅
Best for	Exploratory queries	Specific lookups	Most queries

Pagination

For large result sets, use pagination:

# Get first page
curl -X POST https://api.hypersave.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "meetings", "limit": 20, "offset": 0}'
 
# Get second page
curl -X POST https://api.hypersave.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "meetings", "limit": 20, "offset": 20}'

Error Responses

Empty Query

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Query is required"
}

Invalid Threshold

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Threshold must be between 0 and 1"
}

Ask Query