Ask

POST

/v1/ask

Ask natural language questions about your stored memories. Hypersave uses AI to find relevant content and generate intelligent answers.

Request Body

Parameter	Type	Required	Description
`query`	string	Yes	Your question in natural language
`limit`	number	No	Max memories to consider (default: 10)
`spaceId`	string	No	Limit search to specific space
`filters`	object	No	Additional filters (tags, date range, etc.)
`includeContext`	boolean	No	Include source memories in response (default: false)
`model`	string	No	AI model to use (`default`, `fast`, `smart`)

Examples

Basic Question

curl -X POST https://api.hypersave.io/v1/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "When is the next board meeting?"
  }'

Question with Context

Include the source memories that were used to generate the answer:

curl -X POST https://api.hypersave.io/v1/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were the key decisions from last week?",
    "includeContext": true,
    "limit": 5
  }'

Question with Filters

Filter by tags, date range, or specific space:

curl -X POST https://api.hypersave.io/v1/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the project budget?",
    "filters": {
      "tags": ["finance", "budget"],
      "after": "2024-01-01",
      "before": "2024-12-31"
    }
  }'

Response

Success Response

{
  "success": true,
  "answer": "The next board meeting is scheduled for January 25th at 2:00 PM. The agenda includes quarterly financial review and the new product roadmap presentation.",
  "confidence": 0.92,
  "tokensUsed": 450
}

Response with Context

When includeContext: true:

{
  "success": true,
  "answer": "The next board meeting is scheduled for January 25th at 2:00 PM.",
  "confidence": 0.92,
  "context": [
    {
      "id": "doc_abc123",
      "content": "Board meeting confirmed for January 25th at 2pm. Agenda: Q4 review, product roadmap...",
      "title": "Calendar Update",
      "relevance": 0.95
    },
    {
      "id": "doc_xyz789",
      "content": "Preparing slides for the January board meeting presentation...",
      "title": "Meeting Prep Notes",
      "relevance": 0.78
    }
  ],
  "tokensUsed": 650
}

Response Fields

Field	Type	Description
`answer`	string	AI-generated answer to your question
`confidence`	number	Confidence score (0-1)
`context`	array	Source memories (when `includeContext: true`)
`tokensUsed`	number	Tokens consumed for this request
`noResult`	boolean	True if no relevant information was found

Model Options

Model	Description	Best For
`default`	Balanced speed and quality	Most queries
`fast`	Faster responses, lower quality	Simple questions
`smart`	Higher quality, slower	Complex questions

curl -X POST https://api.hypersave.io/v1/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze the trends in our customer feedback",
    "model": "smart"
  }'

No Results Response

When Hypersave can't find relevant information:

{
  "success": true,
  "answer": "I don't have enough information to answer this question.",
  "noResult": true,
  "suggestion": "Try saving relevant content first, or rephrase your question."
}

If you're getting "no result" responses, try saving more relevant content or use broader search terms in your query.

Error Responses

Empty Query

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

Query Too Long

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Query exceeds maximum length of 1000 characters"
}

Save Search