---
title: "Query memories"
method: POST
path: "/memories/query"
tags: ["Memories"]
---

# Query memories

`POST /memories/query`

Retrieves documents matching the query.

## Request body

- QueryRequest
  - `query` string, required — Query to run.
  - `answer` boolean — If true, the query will be answered along with matching source documents.
  - `provenance` boolean — 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` 'minimal' | 'low' | 'medium' | 'high' | 'very_high' — How much compute the retrieval pipeline should spend on this query. Mirrors the convention popularized by OpenAI's reasoning_effort and similar dials on Anthropic / Gemini APIs. ``minimal`` is the cheapest and fastest path; ``high`` does the most. Tiers map to behavior via ``EFFORT_CONFIG``.
  - `sources` DocumentProviders[] — Only query documents from these sources.
  - `options` QueryOptions
    - `after` string, date-time, nullable — Only query documents created on or after this date.
    - `before` string, date-time, nullable — Only query documents created before this date.
    - `filter` object, nullable — Metadata filters using MongoDB-style operators. Example: {'status': 'published', 'priority': {'$gt': 3}}
    - `resource_ids` string[], nullable — Only return results from these specific resource IDs. Useful for scoping searches to specific documents (e.g., a specific email thread or uploaded file).
    - `memory_types` MemoryType[] — Filter by memory type. Defaults to generic memories only. Pass multiple types to include procedures, etc.
    - `recency_half_life_days` number, nullable — When set, multiplies each result's score by an exponential-decay factor based on the document's most recent activity timestamp (source-reported last_modified, falling back to document_date). A document one half-life old gets its score halved. Resources with no recency timestamp are passed through unchanged. Leave unset to disable.
    - `vault` VaultSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
    - `google_calendar` GoogleCalendarSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `calendar_id` string, nullable — The ID of the calendar to search. If not provided, it will use the ID of the default calendar. You can get the list of calendars with the `/integrations/google_calendar/list` endpoint.
    - `notion` NotionSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `notion_page_ids` string[] — List of Notion page IDs to search. If not provided, all pages in the workspace will be searched.
    - `web_crawler` WebCrawlerSearchOptions — Options for the WebCrawler integration.
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `url` string, nullable — The URL to crawl
      - `max_depth` integer — Maximum depth to crawl from the starting URL
    - `slack` SlackSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `channels` string[] — List of Slack channels to include (by id, name, or #name).
      - `include_private` boolean — Include private channels when constructing Slack 'types'. Defaults to False to preserve existing cassette query params.
      - `include_dms` boolean — Include direct messages (im) when listing conversations.
      - `include_group_dms` boolean — Include group DMs (mpim) when listing conversations.
      - `exclude_archived` boolean, nullable — If set, pass 'exclude_archived' to Slack. If None, omit the param.
    - `box` BoxSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
    - `google_drive` GoogleDriveSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
    - `google_mail` GmailSearchOptions — Search options specific to Gmail integration.
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `label_ids` string[] — List of label IDs to filter messages (e.g., ['INBOX', 'SENT', 'DRAFT']). Multiple labels are combined with OR logic - messages matching ANY specified label will be returned. If empty, no label filtering is applied (searches all accessible messages).
    - `max_results` integer — Maximum number of results to return.
    - `answer_model` 'llama-3.1' | 'gemma2' | 'qwen-qwq' | 'mistral-saba' | 'llama-4-scout' | 'deepseek-r1' | 'gpt-oss-20b' | 'gpt-oss-120b' — Available models for answer generation via AWS Bedrock. Only short, user-friendly names are accepted in API requests. Bedrock model IDs are used internally when calling the Converse API.
  - `max_results` integer — Maximum number of results to return.

## Response `200`

Successful Response

- QueryResult
  - `query_id` string, 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.
  - `errors` object[], 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.
  - `documents` ScoredDocumentResponse[] — The matching documents, each carrying its hyperdoc tree plus query-path score/highlights/summary (ENG-2479 Phase 4).
    - `resource_id` string, required
    - `source` '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' | 'gong', required
    - `type` string, required — Hyperdoc document type discriminator (document, message, file, event, ...).
    - `title` string, nullable — Human-readable document title.
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'
    - `collection` string, nullable — The document's collection, if any.
    - `metadata` object — Filterable custom metadata attached to the document.
    - `ingested_at` string, date-time, nullable — When Hyperspell first indexed the document.
    - `last_modified_at` string, date-time, nullable — When the source document was last modified.
    - `document_date` string, date-time, nullable — The document's own date (e.g. email sent date, event date).
    - `document` union, required — The full hyperdoc tree. Switch on `type` for the document frame and recurse `children` for the body — see the `<Hyperdoc />` renderer.
      - Document
        - `type` 'document'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `title` string, nullable
      - Website
        - `type` 'website'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `url` string, required
        - `description` string, nullable
        - `title` string, nullable
        - `image_url` string, nullable
        - `language` string, nullable
        - `favicon` string, nullable
      - Task
        - `type` 'task'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `comments` Message[], nullable
          - `type` 'message'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, nullable
          - `children` union[]
            - union
              - …
          - `sender` Person, required
            - `type` 'person'
            - `id` string
            - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
              - …
            - `text` string, nullable
            - `children` union[]
              - …
            - `name` string, nullable
            - `email` string, nullable
            - `username` string, nullable
            - `image_url` string, nullable
            - `alt_names` string[], nullable
            - `job_title` string, nullable
            - `company` string, nullable
            - `emails` string[], nullable — All known email addresses; `email` holds the primary one
            - `phone_numbers` string[], nullable
            - `address` string, nullable
            - `tags` string[], nullable
            - `date_of_birth` string, date, nullable
            - `deal_ids` string[], nullable
            - `company_ids` string[], nullable
            - `link_urls` string[], nullable
          - `date` string, date-time, required
          - `title` string, nullable — The subject or title of the message
          - `upvotes` integer, nullable — The number of upvotes, likes, or reactions on the message
          - `replies` Message[], nullable — The replies or comments to the message
          - `channel` string, nullable — The channel or platform where the message was posted, if this Message is not explicitly part of a conversation
          - `external_id` string, nullable — Provider message id (e.g. Slack ts, Gmail message id) — merge-dedup key
          - `is_self` boolean, nullable
          - `updated_at` string, date-time, nullable
          - `num_replies` integer, nullable
          - `thread_id` string, nullable
          - `mentioned_users` Person[], nullable
            - `type` 'person'
            - `id` string
            - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
              - …
            - `text` string, nullable
            - `children` union[]
              - …
            - `name` string, nullable
            - `email` string, nullable
            - `username` string, nullable
            - `image_url` string, nullable
            - `alt_names` string[], nullable
            - `job_title` string, nullable
            - `company` string, nullable
            - `emails` string[], nullable — All known email addresses; `email` holds the primary one
            - `phone_numbers` string[], nullable
            - `address` string, nullable
            - `tags` string[], nullable
            - `date_of_birth` string, date, nullable
            - `deal_ids` string[], nullable
            - `company_ids` string[], nullable
            - `link_urls` string[], nullable
        - `due_at` string, date-time, nullable
        - `status` 'completed' | 'not_started' | 'in_progress' | 'cancelled'
        - `priority` 'urgent' | 'high' | 'medium' | 'low'
      - Person
        - `type` 'person'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `name` string, nullable
        - `email` string, nullable
        - `username` string, nullable
        - `image_url` string, nullable
        - `alt_names` string[], nullable
        - `job_title` string, nullable
        - `company` string, nullable
        - `emails` string[], nullable — All known email addresses; `email` holds the primary one
        - `phone_numbers` string[], nullable
        - `address` string, nullable
        - `tags` string[], nullable
        - `date_of_birth` string, date, nullable
        - `deal_ids` string[], nullable
        - `company_ids` string[], nullable
        - `link_urls` string[], nullable
      - Message
        - `type` 'message'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `sender` Person, required
          - `type` 'person'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, nullable
          - `children` union[]
            - union
              - …
          - `name` string, nullable
          - `email` string, nullable
          - `username` string, nullable
          - `image_url` string, nullable
          - `alt_names` string[], nullable
          - `job_title` string, nullable
          - `company` string, nullable
          - `emails` string[], nullable — All known email addresses; `email` holds the primary one
          - `phone_numbers` string[], nullable
          - `address` string, nullable
          - `tags` string[], nullable
          - `date_of_birth` string, date, nullable
          - `deal_ids` string[], nullable
          - `company_ids` string[], nullable
          - `link_urls` string[], nullable
        - `date` string, date-time, required
        - `title` string, nullable — The subject or title of the message
        - `upvotes` integer, nullable — The number of upvotes, likes, or reactions on the message
        - `replies` Message[], nullable — The replies or comments to the message
        - `channel` string, nullable — The channel or platform where the message was posted, if this Message is not explicitly part of a conversation
        - `external_id` string, nullable — Provider message id (e.g. Slack ts, Gmail message id) — merge-dedup key
        - `is_self` boolean, nullable
        - `updated_at` string, date-time, nullable
        - `num_replies` integer, nullable
        - `thread_id` string, nullable
        - `mentioned_users` Person[], nullable
          - `type` 'person'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, nullable
          - `children` union[]
            - union
              - …
          - `name` string, nullable
          - `email` string, nullable
          - `username` string, nullable
          - `image_url` string, nullable
          - `alt_names` string[], nullable
          - `job_title` string, nullable
          - `company` string, nullable
          - `emails` string[], nullable — All known email addresses; `email` holds the primary one
          - `phone_numbers` string[], nullable
          - `address` string, nullable
          - `tags` string[], nullable
          - `date_of_birth` string, date, nullable
          - `deal_ids` string[], nullable
          - `company_ids` string[], nullable
          - `link_urls` string[], nullable
      - Event
        - `type` 'event'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `title` string, nullable
        - `start_at` string, date-time, nullable
        - `end_at` string, date-time, nullable
        - `meeting_url` string, nullable
        - `location` string, nullable
        - `attendees` Person[]
          - `type` 'person'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, nullable
          - `children` union[]
            - union
              - …
          - `name` string, nullable
          - `email` string, nullable
          - `username` string, nullable
          - `image_url` string, nullable
          - `alt_names` string[], nullable
          - `job_title` string, nullable
          - `company` string, nullable
          - `emails` string[], nullable — All known email addresses; `email` holds the primary one
          - `phone_numbers` string[], nullable
          - `address` string, nullable
          - `tags` string[], nullable
          - `date_of_birth` string, date, nullable
          - `deal_ids` string[], nullable
          - `company_ids` string[], nullable
          - `link_urls` string[], nullable
      - File
        - `type` 'file'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `filename` string, required
        - `content_type` string, required
        - `path` string[], nullable
        - `title` string, nullable
      - Conversation
        - `type` 'conversation'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` Message[]
          - `type` 'message'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, nullable
          - `children` union[]
            - union
              - …
          - `sender` Person, required
            - `type` 'person'
            - `id` string
            - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
              - …
            - `text` string, nullable
            - `children` union[]
              - …
            - `name` string, nullable
            - `email` string, nullable
            - `username` string, nullable
            - `image_url` string, nullable
            - `alt_names` string[], nullable
            - `job_title` string, nullable
            - `company` string, nullable
            - `emails` string[], nullable — All known email addresses; `email` holds the primary one
            - `phone_numbers` string[], nullable
            - `address` string, nullable
            - `tags` string[], nullable
            - `date_of_birth` string, date, nullable
            - `deal_ids` string[], nullable
            - `company_ids` string[], nullable
            - `link_urls` string[], nullable
          - `date` string, date-time, required
          - `title` string, nullable — The subject or title of the message
          - `upvotes` integer, nullable — The number of upvotes, likes, or reactions on the message
          - `replies` Message[], nullable — The replies or comments to the message
          - `channel` string, nullable — The channel or platform where the message was posted, if this Message is not explicitly part of a conversation
          - `external_id` string, nullable — Provider message id (e.g. Slack ts, Gmail message id) — merge-dedup key
          - `is_self` boolean, nullable
          - `updated_at` string, date-time, nullable
          - `num_replies` integer, nullable
          - `thread_id` string, nullable
          - `mentioned_users` Person[], nullable
            - `type` 'person'
            - `id` string
            - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
              - …
            - `text` string, nullable
            - `children` union[]
              - …
            - `name` string, nullable
            - `email` string, nullable
            - `username` string, nullable
            - `image_url` string, nullable
            - `alt_names` string[], nullable
            - `job_title` string, nullable
            - `company` string, nullable
            - `emails` string[], nullable — All known email addresses; `email` holds the primary one
            - `phone_numbers` string[], nullable
            - `address` string, nullable
            - `tags` string[], nullable
            - `date_of_birth` string, date, nullable
            - `deal_ids` string[], nullable
            - `company_ids` string[], nullable
            - `link_urls` string[], nullable
        - `channel` string, nullable
      - Trace — An agent trace/transcript containing a sequence of steps. Steps can be TraceMessage (user/assistant messages or thinking), ToolCall (function calls), or ToolResult (tool responses).
        - `type` 'trace'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
        - `title` string, nullable
      - Transcript — A time-anchored, speaker-attributed transcript — meetings, calls (ENG-2476/D10; mirrors the Trace+TraceStep precedent). Utterance timestamps are relative offsets from `started_at`, which is the absolute wall-clock anchor.
        - `type` 'transcript'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` Utterance[]
          - `type` 'utterance'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, required
          - `speaker` Person
            - `type` 'person'
            - `id` string
            - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
              - …
            - `text` string, nullable
            - `children` union[]
              - …
            - `name` string, nullable
            - `email` string, nullable
            - `username` string, nullable
            - `image_url` string, nullable
            - `alt_names` string[], nullable
            - `job_title` string, nullable
            - `company` string, nullable
            - `emails` string[], nullable — All known email addresses; `email` holds the primary one
            - `phone_numbers` string[], nullable
            - `address` string, nullable
            - `tags` string[], nullable
            - `date_of_birth` string, date, nullable
            - `deal_ids` string[], nullable
            - `company_ids` string[], nullable
            - `link_urls` string[], nullable
          - `start` number, nullable
          - `end` number, nullable
        - `title` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `participants` Person[]
          - `type` 'person'
          - `id` string
          - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
            - `sources` SourceRef[], nullable
              - …
            - `edited_by` string, nullable
          - `text` string, nullable
          - `children` union[]
            - union
              - …
          - `name` string, nullable
          - `email` string, nullable
          - `username` string, nullable
          - `image_url` string, nullable
          - `alt_names` string[], nullable
          - `job_title` string, nullable
          - `company` string, nullable
          - `emails` string[], nullable — All known email addresses; `email` holds the primary one
          - `phone_numbers` string[], nullable
          - `address` string, nullable
          - `tags` string[], nullable
          - `date_of_birth` string, date, nullable
          - `deal_ids` string[], nullable
          - `company_ids` string[], nullable
          - `link_urls` string[], nullable
      - Company — A CRM company/account record (ENG-2476/D10).
        - `type` 'company'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `name` string, nullable
        - `description` string, nullable
        - `industry` string, nullable
        - `employees` integer, nullable
        - `websites` string[], nullable
        - `emails` string[], nullable
        - `phone_numbers` string[], nullable
        - `address` string, nullable
        - `image_url` string, nullable
        - `is_active` boolean, nullable
        - `tags` string[], nullable
        - `timezone` string, nullable
        - `deal_ids` string[], nullable
        - `contact_ids` string[], nullable
      - Deal — A CRM deal/opportunity record (ENG-2476/D10).
        - `type` 'deal'
        - `id` string
        - `metadata` Metadata — Per-block annotations carried by any Hyperdoc node (ENG-1390). Out-of-band annotations that travel with a block but aren't part of its content: provenance (`sources`) and human edit attribution (`edited_by`). New annotation types get added here as typed fields as the need arises. Empty by default. Because `Node.model_dump` forces `exclude_none=True`, an unset `metadata` (None) is dropped from serialization entirely, and within a populated `Metadata` only the set keys survive.
          - `sources` SourceRef[], nullable
            - `chunk_id` string, required
            - `resource_id` string, nullable
            - `source` string, nullable
            - `score` number, nullable
          - `edited_by` string, nullable
        - `text` string, nullable
        - `children` union[]
          - union
            - Blob — Represents embedded binary data using data URI scheme. Format: data:[<media type>][;base64],<data> Example: data:text/html;base64,PGh0bWw+...
              - …
            - Callout
              - …
            - Chunk
              - …
            - Code
              - …
            - Comment
              - …
            - Divider
              - …
            - Equation
              - …
            - Footnote
              - …
            - Heading
              - …
            - Image
              - …
            - Link
              - …
            - LineBreak
              - …
            - List
              - …
            - ListItem
              - …
            - Paragraph
              - …
            - Quote
              - …
            - Table
              - …
            - TableCell
              - …
            - TableRow
              - …
            - Text
              - …
            - ToDo
              - …
            - ToolCall — A tool/function call made by the assistant.
              - …
            - ToolResult — The result of a tool call.
              - …
            - TraceMessage — A message in an agent trace (user message, assistant message, or thinking).
              - …
            - Utterance — A speaker-attributed segment of a transcript (ENG-2476/D10). "Utterance" is the standard name for this across transcription providers (AssemblyAI, Deepgram, Rev). Timestamps are relative offsets in seconds — provider-native; absolute times derive from `Transcript.started_at`.
              - …
        - `name` string, nullable
        - `amount` number, nullable
        - `currency` string, nullable
        - `stage` string, nullable
        - `pipeline` string, nullable
        - `probability` number, nullable
        - `closed_at` string, date-time, nullable
        - `won_reason` string, nullable
        - `lost_reason` string, nullable
        - `deal_source` string, nullable
        - `tags` string[], nullable
        - `company_ids` string[], nullable
        - `contact_ids` string[], nullable
    - `score` number, nullable — Relevance of the document to the query.
    - `highlights` Highlight[] — The matched chunks that made this document a hit, with per-chunk scores.
      - unknown
    - `summary` string, nullable — Concatenated text of the matched highlights.
  - `answer` string, nullable — The answer to the query, if the request was set to answer.
  - `provenance` Provenance — Auditability record attached to an agentic answer. Gated behind ``provenance=true`` on the request: the cheap parts (sources, steps, failed_sources) are derived from in-memory loop state, but ``entities`` costs one indexed DB lookup, so the whole record is only built on request.
    - `sources` ProvenanceSource[]
      - `source` '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' | 'gong', required
      - `resource_id` string, required
      - `title` string, nullable
      - `score` number, nullable
    - `entities` ProvenanceEntity[]
      - `id` string, uuid, required
      - `name` string, required
      - `type` string, required
    - `failed_sources` string[]
    - `steps` ProvenanceStep[]
      - `iteration` integer, required
      - `tool` string, required
      - `query` string, nullable
      - `source` string, nullable
      - `result_count` integer
      - `status` string, required
  - `score` number, nullable — The average score of the query feedback, if any.
  - `query` string, nullable — The query string that was issued.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/hyperspell/apis/hyperspell-api.md) · [All operations](https://skmtc.net/hyperspell/apis/hyperspell-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hyperspell/hyperspell-api/revisions/5721acd588e6/schema)