Skip to main content
POST
/
memories
/
query
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);
{
  "query_id": "<string>",
  "errors": [
    {}
  ],
  "documents": [
    {
      "resource_id": "<string>",
      "type": "<string>",
      "document": {
        "type": "document",
        "id": "<string>",
        "metadata": {
          "sources": [
            {
              "chunk_id": "<string>",
              "resource_id": "<string>",
              "source": "<string>",
              "score": 123
            }
          ],
          "edited_by": "<string>"
        },
        "text": "<string>",
        "children": [
          {
            "mimetype": "<string>",
            "data": "<string>",
            "type": "blob",
            "id": "<string>",
            "metadata": {
              "sources": [
                {
                  "chunk_id": "<string>",
                  "resource_id": "<unknown>",
                  "source": "<unknown>",
                  "score": "<unknown>"
                }
              ],
              "edited_by": "<string>"
            }
          }
        ],
        "title": "<string>"
      },
      "title": "<string>",
      "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",
      "score": 123,
      "highlights": [
        "<unknown>"
      ],
      "summary": "<string>"
    }
  ],
  "answer": "<string>",
  "provenance": {
    "sources": [
      {
        "resource_id": "<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
      }
    ]
  },
  "score": 123,
  "query": "<string>"
}

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.

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.

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. Adds one indexed lookup; intended for auditability / compliance use cases.

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,
very_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,
fireflies,
linear,
hubspot,
salesforce,
coda,
lightfield
options
QueryOptions · object

Search options for the query.

max_results
integer
default:10
deprecated

Maximum number of results to return.

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/summary (ENG-2479 Phase 4).

answer
string | null

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

provenance
Provenance · object

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.