Welcome
Use the Hyperspell API to add memories, connect data sources, and search your users’ data using natural language. You can add data directly or let users connect services such as Notion, Gmail, and Slack.Authentication
Hyperspell API requests use bearer-token authentication. Generate an API key in the Hyperspell dashboard, then send it asAuthorization: Bearer <key> with every request. Keys created in the admin API Keys settings act for the whole organization. Keys created from Connect Agents act as the member who created them. See Permissions for what each can see.
Search response content
POST /memories/query returns matched text in highlights, alongside a small
typed document frame. Search results do not include complete parent documents
or channel histories. body_status: "excerpt" means source evidence is present;
"omitted" means the result contains only its envelope or generated summaries.
These values describe the response, not whether the stored document is complete.
The document keeps its display title (or name) and an explicit empty children
array; render matched text from highlights. Short highlight feedback comments
are preserved when they fit alongside the matched text.
Each document record is limited to 32 KiB, including up to 8 KiB of excerpts and
a display title of up to 1 KiB. At most three highlights are returned, with up to
2,000 characters each including any abbreviation marker. These delivery ceilings
are independent of retrieval candidate limits. The document-array budget scales with the requested
result count: 256 KiB for 10 results, 800 KiB for 50, and 3,200 KiB for 200.
The public header X-Hyperspell-Response-Profile: mcp selects a fixed 256 KiB
document-array budget. Use lowercase api or mcp; other values return HTTP 422.
SDK callers can send this header using their request-header override.
When limits require content reductions or fewer results, the HTTP response remains
200 and includes ResponseContentLimited in the existing errors array. This is
an informational outcome. It does not mean search or answer generation failed.
The answer, query ID, other outcomes, and retained results’ identities and scores
are preserved. Optional metadata is reduced before dropping results. Always use
source and resource_id for identity; displayed titles may be abbreviated.
These limits cover returned document records. Answer text, provenance, and
upstream retrieval have separate limits. They do not change permissions or the
number of candidates considered by retrieval and reranking.
This section applies specifically to POST /memories/query. Saved-query reads
at GET /evaluate/query/{query_id}, point reads, and live document endpoints
have separate response policies; sharing a response model does not apply these
query limits to them.
Listing documents
GET /memories/list returns document envelopes by default. These body-free records
report body_status: "omitted". Each record is limited to 32 KiB, with a bounded
display title; large optional metadata, summaries, or document-frame fields may be
omitted. A notices entry with code: "ResponseContentLimited" identifies such
reductions. Stored content and permissions are unchanged.
The default page budget scales with size: 256 KiB for small pages, up to 1,600 KiB
for 100 results. To request a smaller 256 KiB page budget, send the public header
X-Hyperspell-Response-Profile: mcp. The header changes response size, not access.
SDK requests can send the same header through their request-header override.
Values are case-sensitive: use lowercase api or mcp. Other values return HTTP 422.
next_cursor when present, including after a short or empty
page. A record that cannot fit even an empty page is explicitly skipped in
notices, with its exact identity when that identity fits. Do not treat a short
page as the end of the listing.
include_body=true and single-document fetches retain their separate read behavior
and do not yet enforce these body-free listing limits. They do not gain a new
completeness guarantee from the response-profile header.