curl --request POST \
--url https://api.hyperspell.com/memories/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"answer": true,
"options": {
"filter": {}
},
"query": "What does Hyperspell do?",
"sources": [
"vault"
]
}
'import requests
url = "https://api.hyperspell.com/memories/query"
payload = {
"answer": True,
"options": { "filter": {} },
"query": "What does Hyperspell do?",
"sources": ["vault"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
answer: true,
options: {filter: {}},
query: 'What does Hyperspell do?',
sources: ['vault']
})
};
fetch('https://api.hyperspell.com/memories/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperspell.com/memories/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'answer' => true,
'options' => [
'filter' => [
]
],
'query' => 'What does Hyperspell do?',
'sources' => [
'vault'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hyperspell.com/memories/query"
payload := strings.NewReader("{\n \"answer\": true,\n \"options\": {\n \"filter\": {}\n },\n \"query\": \"What does Hyperspell do?\",\n \"sources\": [\n \"vault\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hyperspell.com/memories/query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"answer\": true,\n \"options\": {\n \"filter\": {}\n },\n \"query\": \"What does Hyperspell do?\",\n \"sources\": [\n \"vault\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperspell.com/memories/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"answer\": true,\n \"options\": {\n \"filter\": {}\n },\n \"query\": \"What does Hyperspell do?\",\n \"sources\": [\n \"vault\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"query_id": "<string>",
"errors": [
{}
],
"documents": [
{
"resource_id": "<string>",
"source": "reddit",
"type": "<string>",
"document": {
"children": [
{
"text": "The next release adds calendar search.",
"type": "text"
}
],
"title": "Project notes",
"type": "document"
},
"body_status": "full",
"title": "<string>",
"status": "pending",
"collection": "<string>",
"metadata": {},
"ingested_at": "2023-11-07T05:31:56Z",
"last_modified_at": "2023-11-07T05:31:56Z",
"document_date": "2023-11-07T05:31:56Z",
"chunks": [
{
"chunk_id": "<string>",
"summary": "<string>"
}
],
"score": 123,
"highlights": [
"<unknown>"
],
"summary": "<string>"
}
],
"answer": "<string>",
"disclaimer": "<string>",
"provenance": {
"sources": [
{
"source": "reddit",
"resource_id": "<string>",
"owner": "<string>",
"chunk_id": "<string>",
"span": [
0,
120
],
"content_sha256": "<string>",
"title": "<string>",
"score": 123
}
],
"entities": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"type": "<string>"
}
],
"failed_sources": [
"<string>"
],
"steps": [
{
"iteration": 123,
"tool": "<string>",
"status": "<string>",
"query": "<string>",
"source": "<string>",
"result_count": 0
}
],
"entity_searches": [
{
"surface": "<string>",
"entity_type": "<string>",
"query": "<string>",
"partial": false,
"matches": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"type": "<string>",
"match_kind": "<string>",
"sources": [
{
"source": "reddit",
"resource_id": "<string>",
"owner": "<string>",
"chunk_id": "<string>",
"span": [
0,
120
],
"content_sha256": "<string>"
}
],
"context": [
{
"source": "reddit",
"resource_id": "<string>",
"chunk_id": "<string>",
"text": "<string>",
"owner": "<string>",
"span": [
0,
120
],
"content_sha256": "<string>",
"title": "<string>",
"kind": "retrieved_context",
"mention": "<string>",
"observed_surface": "<string>"
}
]
}
],
"passage_mapping": "unavailable"
}
],
"entity_resolutions": [
{
"reference": "<string>",
"status": "complete",
"candidates": [
{
"entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"canonical_name": "<string>",
"entity_type": "<string>",
"reason": "<string>",
"evidence": [
{
"source": "reddit",
"resource_id": "<string>",
"text": "<string>",
"chunk_id": "<string>"
}
],
"description": "<string>"
}
],
"limitations": [
"<string>"
]
}
]
},
"score": 123,
"query": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Query memories
Retrieves documents matching the query.
curl --request POST \
--url https://api.hyperspell.com/memories/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"answer": true,
"options": {
"filter": {}
},
"query": "What does Hyperspell do?",
"sources": [
"vault"
]
}
'import requests
url = "https://api.hyperspell.com/memories/query"
payload = {
"answer": True,
"options": { "filter": {} },
"query": "What does Hyperspell do?",
"sources": ["vault"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
answer: true,
options: {filter: {}},
query: 'What does Hyperspell do?',
sources: ['vault']
})
};
fetch('https://api.hyperspell.com/memories/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperspell.com/memories/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'answer' => true,
'options' => [
'filter' => [
]
],
'query' => 'What does Hyperspell do?',
'sources' => [
'vault'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hyperspell.com/memories/query"
payload := strings.NewReader("{\n \"answer\": true,\n \"options\": {\n \"filter\": {}\n },\n \"query\": \"What does Hyperspell do?\",\n \"sources\": [\n \"vault\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hyperspell.com/memories/query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"answer\": true,\n \"options\": {\n \"filter\": {}\n },\n \"query\": \"What does Hyperspell do?\",\n \"sources\": [\n \"vault\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperspell.com/memories/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"answer\": true,\n \"options\": {\n \"filter\": {}\n },\n \"query\": \"What does Hyperspell do?\",\n \"sources\": [\n \"vault\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"query_id": "<string>",
"errors": [
{}
],
"documents": [
{
"resource_id": "<string>",
"source": "reddit",
"type": "<string>",
"document": {
"children": [
{
"text": "The next release adds calendar search.",
"type": "text"
}
],
"title": "Project notes",
"type": "document"
},
"body_status": "full",
"title": "<string>",
"status": "pending",
"collection": "<string>",
"metadata": {},
"ingested_at": "2023-11-07T05:31:56Z",
"last_modified_at": "2023-11-07T05:31:56Z",
"document_date": "2023-11-07T05:31:56Z",
"chunks": [
{
"chunk_id": "<string>",
"summary": "<string>"
}
],
"score": 123,
"highlights": [
"<unknown>"
],
"summary": "<string>"
}
],
"answer": "<string>",
"disclaimer": "<string>",
"provenance": {
"sources": [
{
"source": "reddit",
"resource_id": "<string>",
"owner": "<string>",
"chunk_id": "<string>",
"span": [
0,
120
],
"content_sha256": "<string>",
"title": "<string>",
"score": 123
}
],
"entities": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"type": "<string>"
}
],
"failed_sources": [
"<string>"
],
"steps": [
{
"iteration": 123,
"tool": "<string>",
"status": "<string>",
"query": "<string>",
"source": "<string>",
"result_count": 0
}
],
"entity_searches": [
{
"surface": "<string>",
"entity_type": "<string>",
"query": "<string>",
"partial": false,
"matches": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"type": "<string>",
"match_kind": "<string>",
"sources": [
{
"source": "reddit",
"resource_id": "<string>",
"owner": "<string>",
"chunk_id": "<string>",
"span": [
0,
120
],
"content_sha256": "<string>"
}
],
"context": [
{
"source": "reddit",
"resource_id": "<string>",
"chunk_id": "<string>",
"text": "<string>",
"owner": "<string>",
"span": [
0,
120
],
"content_sha256": "<string>",
"title": "<string>",
"kind": "retrieved_context",
"mention": "<string>",
"observed_surface": "<string>"
}
]
}
],
"passage_mapping": "unavailable"
}
],
"entity_resolutions": [
{
"reference": "<string>",
"status": "complete",
"candidates": [
{
"entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"canonical_name": "<string>",
"entity_type": "<string>",
"reason": "<string>",
"evidence": [
{
"source": "reddit",
"resource_id": "<string>",
"text": "<string>",
"chunk_id": "<string>"
}
],
"description": "<string>"
}
],
"limitations": [
"<string>"
]
}
]
},
"score": 123,
"query": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
API Key or JWT User Token. If using an API Key, set the X-As-User header to act as a specific user. A JWT User Token is always scoped to a specific user.
Headers
Document response budget: lowercase api scales with the requested result count; lowercase mcp uses 256 KiB. Values are case-sensitive. This does not change access permissions or retrieval depth.
api, mcp Optionally set this header to act as a specific user when using an API Key, equivalent to first exchanging the API Key for a User Token
Body
Memory-query payload; serialized request bodies are capped at 1 MiB.
Query to run.
If true, the query will be answered along with matching source documents.
If true (effort='very_high' only), attach a provenance record to the response: the source documents and entities the answer was grounded in, the agent's search trajectory, and any sources that failed. Intended for auditability and compliance use cases.
Controls retrieval thoroughness. 'minimal' performs direct retrieval. 'low' improves the query and extracts date filters. 'medium' adds up to 3 refinement rounds; 'high' allows up to 6. Higher levels can improve recall but add latency and cost.
minimal, low, medium, high, very_high Only query documents from these sources. Names are case-insensitive and accept either separator, so Google Drive's provider may be given as google_drive, google-drive, or GOOGLE_DRIVE.
reddit, notion, slack, google_calendar, google_mail, imap, google_meet, box, dropbox, github, gitlab, google_drive, vault, web_crawler, trace, microsoft_outlook, microsoft_teams, granola, fathom, fireflies, figma, linear, hubspot, salesforce, coda, confluence, jira, metabase, gong, clickup, lightfield, pylon, fellow, odoo, external_mcp, page Search options for the query.
Show child attributes
Show child attributes
Maximum number of results to return.
1 <= x <= 200Response
Successful Response
The ID of the query. This can be used to retrieve the query later, or add feedback to it. If the query failed, this will be None.
Errors that occurred during the query. These are meant to help the developer debug the query, and are not meant to be shown to the user.
Show child attributes
Show child attributes
The matching documents, each carrying its hyperdoc tree plus query-path score, highlights, and summary.
Show child attributes
Show child attributes
The answer to the query, if the request was set to answer.
Privacy notice for the answer, when applicable. If present, callers must display it alongside the answer.
Auditability record (source documents, entities, search trajectory, failed sources), if the request set provenance=True on a very_high query.
Show child attributes
Show child attributes
The average score of the query feedback, if any.
The query string that was issued.
Was this page helpful?