Query memories

Retrieves documents matching the query.

POST /memories/query

JavaScript

JavaScript

import Hyperspell from '@hyperspell/hyperspell';

const client = new Hyperspell({
  apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted
});

const queryResult = await client.memories.search({ query: 'What does Hyperspell do?' });

console.log(queryResult.query_id);

200

{
  "documents": [
    {
      "resource_id": "<string>",
      "title": "<string>",
      "metadata": {
        "created_at": "2023-11-07T05:31:56Z",
        "indexed_at": "2023-11-07T05:31:56Z",
        "last_modified": "2023-11-07T05:31:56Z",
        "status": "pending",
        "events": [
          {
            "message": "<string>",
            "time": "2023-11-07T05:31:56Z"
          }
        ],
        "url": "<string>"
      },
      "score": 123,
      "folder_id": "<string>",
      "parent_folder_id": "<string>",
      "folder_ancestors": [
        "<string>"
      ]
    }
  ],
  "query_id": "<string>",
  "errors": [
    {}
  ],
  "answer": "<string>",
  "score": 123
}

Authorizations

APIKeyAsUser

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.

Body

application/json

query · string · required

Query to run.

answer · boolean · default: false

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

effort · enum<string> · default: minimal

How much compute to spend on retrieval. Mirrors the dial popularized by frontier-model APIs (OpenAI reasoning_effort, etc.). 'minimal' = verbatim single-shot retrieval (fastest). 'low' = LLM rewrites the query for better retrieval and extracts date filters. 'medium' = rewrite + agentic refinement loop (the answer LLM may request additional retrieval rounds, up to 3). 'high' = rewrite + extended refinement (up to 6 rounds). Higher = better recall, more latency, more cost.

Available options: minimal, low, medium, high

sources · enum<string>[]

Only query documents from these sources.

Available options: reddit, notion, slack, google_calendar, google_mail, box, dropbox, github, google_drive, vault, web_crawler, trace, microsoft_teams, gmail_actions, granola, fathom, linear, hubspot, salesforce, coda

options · QueryOptions · object

Search options for the query.

Show child attributes

max_results · integer · default: 10 · deprecated

Maximum number of results to return.

Response

200

application/json

Successful Response

documents · Resource · object[] · required

Show child attributes

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

answer · string | null

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

score · number | null

The average score of the query feedback, if any.