Skip to main content

​
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 as Authorization: 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. 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.

​
Query provenance

Every query response includes provenance.turns, an ordered array. Request provenance: true at any effort to collect model turns and their tool outcomes. In the CLI, use hyperbrain ask "your question" --provenance -o json.
Each turn represents a model response. A final answer can have no tool calls. Very High includes native provider reasoning summaries when available; other turns retain a null summary. These summaries are model commentary, may discuss authorized evidence beyond the final returned documents, and are not verified findings or citations. They add no separate summarization call. Without collected turns, the array is empty. Existing flat provenance.steps remains available. For effort: "very_high", request provenance: true to inspect the returned source evidence and search trajectory. In the CLI, use hyperbrain ask "your question" -e very_high --provenance -o json. When entity-assisted search is enabled, entity_resolutions contains possible identity matches, their supporting excerpts, status, and limitations. A match does not confirm a role, relationship, or presence in the final documents. The legacy entity_searches field is omitted and entities is empty on this path, even when the agent used identity lookup. Neither value means that no lookup ran. For each search_indexed step, entity_filter_requested reports whether the agent supplied an entity restriction. Check the step’s status to distinguish successful, empty, and failed attempts. This flag does not expose entity IDs or claim that a candidate appeared in the answer. Older records may omit the flag. Retain the original response if you need this audit trail. Saved-query reads currently return the saved answer and accessible source results, but do not reconstruct the original tool trajectory or identity lookup provenance.

​
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. Values are case-sensitive: use lowercase api or mcp. Other values return HTTP 422.
Always continue using 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 uses the same record and page limits. Small non-channel documents may include a stored body labeled body_status: "preview"; larger or restricted bodies are omitted with a notice. Slack and Teams history and File previews remain excluded from listings. Optional bodies never displace required records. Use GET /memories/get/{source}/{resource_id} or MCP get_memory for a larger bounded preview or channel page. A preview does not guarantee completeness.

​
Reading indexed channel content

GET /memories/get/{source}/{resource_id} returns a bounded page for Slack and Microsoft Teams. The document tree contains permitted indexed source content; it never loads the stored channel history to fill the response. Each page is at most 32 KiB, including optional chunk summaries and notices. body_status is preview when source content is present and omitted otherwise. The notices array explains partial content and reports skipped_chunk_count for oversized or unreadable chunks. A generated summary is not substituted for source content. A final page does not imply that the entire provider history was ingested. Pass next_cursor back as the cursor query parameter to continue, even after an empty page. Authorization is checked again on every request. Pagination follows the current index, so concurrent ingestion or replacement can change later pages. The dashboard replaces each page rather than accumulating the entire channel. The public X-Hyperspell-Response-Profile header accepts lowercase api (default) or mcp; both use the same 32 KiB channel-page cap. Other values return HTTP 422. Other providers reject a channel cursor.

​
Reading other indexed documents

Single-document reads from other providers return at most 1 MiB of JSON with the api profile, or 256 KiB with mcp. These limits include the document envelope, optional chunk summaries, and notices. MCP selects its profile before the backend loads content. Responses use body_status=preview when source content is available and omitted otherwise, with a ResponseContentLimited notice explaining the bounded view. A preview does not prove that the full original source was indexed or returned. Non-channel previews do not provide continuation in this release. Uploaded files use their stored readable preview, not a reconstruction from search chunks. A large preview can return a shorter source-text prefix. Its stored content_truncated flag describes ingestion, independently of response clipping. If chunk exclusions prevent safely exposing the stored body, the file can return an omitted body. Other documents use permitted indexed content, or a bounded stored body when no source-bearing chunks or exclusions prevent that fallback. The dashboard displays these notices beside the content. Original-file downloads, and live-provider reads retain their separate contracts.

​
Direct Fathom, Fellow and Gong transcript reads

GET /live/fathom/resources/{resource_id}, GET /live/fellow/resources/{resource_id} and GET /live/gong/resources/{resource_id} return a transcript preview with meeting dates, attributed utterances and relative timestamps. Each record fits within 32 KiB; the whole response fits within 1 MiB for the default api profile or 256 KiB with X-Hyperspell-Response-Profile: mcp. Large transcripts can have shortened text or an omitted tail and participant roster. Retained utterances keep their IDs, speakers and timestamps. Read notes for reductions; body_status is preview, or omitted when no body fits. There is no continuation cursor, and even a small preview does not guarantee the complete original transcript. Provider responses over 2 MiB (api) or 512 KiB (mcp), over 100 media items or 1,000 combined entries fail with HTTP 422. Fathom counts transcript turns, action items and a nonempty summary object. Fellow counts transcript turns, AI-note templates, sections, list content entries, bullet points and assignees together, including empty entries and inactive templates. Gong counts inline transcript turns, including empty turns; a transcript available only through a download URL fails with 422 because direct reads do not follow those URLs. Redirected or compressed provider responses and oversized identity frames also fail with 422. index=false is the default; when a resource is returned, index=true queues the existing full background fetch for indexing. These limits apply to direct live API reads and do not change background ingestion or ordinary memory queries.