Skip to main content
POST
Query memories

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 (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.

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.

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.

documents
ScoredDocumentResponse · object[]

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

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 | null

Auditability record (source documents, entities, search trajectory, failed sources), if the request set provenance=True on a very_high query.

score
number | null

The average score of the query feedback, if any.

query
string | null

The query string that was issued.