Query

POST

/v1/query

Advanced query endpoint with support for complex filters, aggregations, and full-text search. Use this for programmatic access to your memories.

Request Body

Parameter	Type	Required	Description
`query`	string	No	Search query text
`filters`	object	No	Complex filter conditions
`sort`	object	No	Sort configuration
`limit`	number	No	Max results (default: 20, max: 100)
`offset`	number	No	Pagination offset
`fields`	string[]	No	Fields to return
`aggregate`	object	No	Aggregation settings

Filter Operators

Operator	Description	Example
`$eq`	Equals	`{"tag": {"$eq": "important"}}`
`$ne`	Not equals	`{"status": {"$ne": "archived"}}`
`$gt`	Greater than	`{"score": {"$gt": 0.8}}`
`$gte`	Greater than or equal	`{"score": {"$gte": 0.5}}`
`$lt`	Less than	`{"createdAt": {"$lt": "2024-01-01"}}`
`$lte`	Less than or equal	`{"createdAt": {"$lte": "2024-12-31"}}`
`$in`	In array	`{"tag": {"$in": ["a", "b"]}}`
`$nin`	Not in array	`{"tag": {"$nin": ["spam"]}}`
`$and`	Logical AND	`{"$and": [{...}, {...}]}`
`$or`	Logical OR	`{"$or": [{...}, {...}]}`

Examples

Basic Query

curl -X POST https://api.hypersave.io/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project updates",
    "limit": 10
  }'

Complex Filter Query

curl -X POST https://api.hypersave.io/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "$and": [
        {"tags": {"$in": ["important", "urgent"]}},
        {"createdAt": {"$gte": "2024-01-01"}},
        {"metadata.status": {"$ne": "archived"}}
      ]
    },
    "sort": {"createdAt": -1},
    "limit": 20
  }'

Query with Field Selection

Return only specific fields to reduce response size:

curl -X POST https://api.hypersave.io/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "meetings",
    "fields": ["id", "title", "createdAt"],
    "limit": 50
  }'

Query with Aggregation

Get statistics about your memories:

curl -X POST https://api.hypersave.io/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": {
      "countByTag": true,
      "dateHistogram": {
        "field": "createdAt",
        "interval": "week"
      }
    }
  }'

Response

Basic Response

{
  "success": true,
  "results": [
    {
      "id": "doc_abc123",
      "content": "Weekly project update: Completed milestone 3...",
      "title": "Project Update Week 4",
      "tags": ["project", "weekly-update"],
      "createdAt": "2024-01-28T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 45,
    "hasMore": true
  }
}

Response with Aggregations

{
  "success": true,
  "results": [...],
  "aggregations": {
    "countByTag": {
      "project": 25,
      "meeting": 18,
      "research": 12
    },
    "dateHistogram": [
      {"date": "2024-01-01", "count": 15},
      {"date": "2024-01-08", "count": 22},
      {"date": "2024-01-15", "count": 18}
    ]
  },
  "pagination": {...}
}

Sorting

Sort results by any field:

{
  "sort": {
    "createdAt": -1  // -1 for descending, 1 for ascending
  }
}

Multiple sort fields:

{
  "sort": {
    "metadata.priority": -1,
    "createdAt": -1
  }
}

Default sort is by relevance score when a query is provided, otherwise by createdAt descending.

Error Responses

Invalid Filter

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Invalid filter operator: $unknown"
}

Invalid Field

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field in filters: invalidField"
}

Search Memories