Query memories

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,
      "url": "<string>",
      "matched_at": "2023-11-07T05:31:56Z",
      "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>",
        "reference": "<string>",
        "reason": "<string>",
        "evidence": [
          {
            "source": "reddit",
            "resource_id": "<string>",
            "text": "<string>",
            "chunk_id": "<string>"
          }
        ],
        "searched": true
      }
    ],
    "failed_sources": [
      "<string>"
    ],
    "steps": [
      {
        "iteration": 123,
        "tool": "<string>",
        "status": "<string>",
        "query": "<string>",
        "source": "<string>",
        "explanation": "<string>",
        "entity_filter_requested": true,
        "result_count": 0
      }
    ],
    "turns": [
      {
        "iteration": 1,
        "reasoning_summary": "<string>",
        "tool_calls": [
          {
            "iteration": 123,
            "tool": "<string>",
            "status": "<string>",
            "query": "<string>",
            "source": "<string>",
            "explanation": "<string>",
            "entity_filter_requested": true,
            "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>",
            "reference": "<string>",
            "reason": "<string>",
            "evidence": [
              {
                "source": "reddit",
                "resource_id": "<string>",
                "text": "<string>",
                "chunk_id": "<string>"
              }
            ],
            "searched": true,
            "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>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

POST

memories

query

Query memories

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,
      "url": "<string>",
      "matched_at": "2023-11-07T05:31:56Z",
      "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>",
        "reference": "<string>",
        "reason": "<string>",
        "evidence": [
          {
            "source": "reddit",
            "resource_id": "<string>",
            "text": "<string>",
            "chunk_id": "<string>"
          }
        ],
        "searched": true
      }
    ],
    "failed_sources": [
      "<string>"
    ],
    "steps": [
      {
        "iteration": 123,
        "tool": "<string>",
        "status": "<string>",
        "query": "<string>",
        "source": "<string>",
        "explanation": "<string>",
        "entity_filter_requested": true,
        "result_count": 0
      }
    ],
    "turns": [
      {
        "iteration": 1,
        "reasoning_summary": "<string>",
        "tool_calls": [
          {
            "iteration": 123,
            "tool": "<string>",
            "status": "<string>",
            "query": "<string>",
            "source": "<string>",
            "explanation": "<string>",
            "entity_filter_requested": true,
            "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>",
            "reference": "<string>",
            "reason": "<string>",
            "evidence": [
              {
                "source": "reddit",
                "resource_id": "<string>",
                "text": "<string>",
                "chunk_id": "<string>"
              }
            ],
            "searched": true,
            "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>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

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

X-Hyperspell-Response-Profile

enum<string>

default:api

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.

Available options:

api,

mcp

X-As-User

string | null

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

application/json

Memory-query payload; serialized request bodies are capped at 1 MiB.

query

string

required

Query to run.

answer

boolean

default:false

If true, the query will be answered along with matching source documents.

provenance

boolean

default:false

If true, collect model turns and tool outcomes in the provenance record. At medium effort and above, provenance.entities also lists entities: possible identity matches from lookups during search, or else the entities in the returned documents.

body_mode

enum<string>

default:auto

How much source content each returned document carries. 'auto' and 'excerpt' include the matched highlights and summary; 'none' returns references only (title, source, id, date, score and link), with body_status set to 'omitted'. The answer and the documents it is built from are the same in every mode.

Available options:

auto,

excerpt,

none

effort

enum<string>

default:minimal

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.

Available options:

minimal,

low,

medium,

high,

very_high

sources

enum<string>[]

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.

Available options:

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

options

QueryOptions · object

Search options for the query.

Show child attributes

max_results

integer

default:10

deprecated

Maximum number of results to return.

Required range: 1 <= x <= 200

Response

Successful Response

query_id

string | null

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

Errors · object[] | null

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

documents

ScoredDocumentResponse · object[]

The matching documents, each carrying its hyperdoc tree plus query-path score, highlights, and summary.

Show child attributes

answer

string | null

The answer to the query, if the request was set to answer.

disclaimer

string | null

Privacy notice for the answer, when applicable. If present, callers must display it alongside the answer.

provenance

Provenance · object

Query provenance with a consistent turns array. Turn details are collected when provenance=True. At medium effort and above, entities lists possible identity matches from lookups during search, or else the entities in the returned documents.

Show child attributes

score

number | null

deprecated

Deprecated: the average score of the query feedback. Only saved-query reads set it; a future release moves it to a separate saved-query response.

query

string | null

deprecated

Deprecated: the query string that was issued. Only saved-query reads set it; a future release moves it to a separate saved-query response.

API Documentation

Memories

Messages

Traces

Live

Evaluation

Authentication

Users

Device Auth

Integrations

Connections

Folder Policies

Folders

OAuth

Vault

Emotional State

entities

Actions

Query memories

Authorizations

Headers

Body

Response