Memories

Query memories

Changed on

Retrieves documents matching the query.

post/memories/query

Request

  • Base URL
    https://api.hyperspell.com
  • URL
    https://api.hyperspell.com/memories/query
  • Auth
    HTTP bearer

Headers

X-Hyperspell-Response-Profile'api' | 'mcp'

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.

X-As-Userstring nullable

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

Request body

querystring required

Query to run.

answerboolean

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

provenanceboolean

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.

effort'minimal' | 'low' | 'medium' | 'high' | 'very_high'

How much compute to spend on a query.

minimal favors speed and cost, while higher levels perform more retrieval and refinement for complex questions.

sourcesDocumentProviders[]

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.

max_resultsinteger

Maximum number of results to return.

Example request

{
  "answer": true,
  "options": {
    "filter": {}
  },
  "query": "What does Hyperspell do?",
  "sources": [
    "vault"
  ]
}

Response

Successful Response

query_idstring nullable

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.

errorsobject[] nullable

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.

answerstring nullable

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

disclaimerstring nullable

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

provenanceProvenance (unresolved $ref)
scorenumber nullable

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.

querystring nullable

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

Changes

  • 5721acd588e6Revision changes
    • warning

      removed the request property /

  • 77d3e8d5e8a7Revision changes
    • warning

      added the new gong enum value to the // response property for the response status

    • warning

      added the new gong enum value to the //// response property for the response status

    • info

      added the new gong enum value to the request property /