---
title: "Extended Search Notes"
method: POST
path: "/v2/notes/extended-search"
tags: ["external", "external-v2"]
---

# Extended Search Notes

`POST /v2/notes/extended-search`

Search notes and note-linked attachments together.
Returns note hits with attachment match context for PDFs, images, audio
recordings, calendar events, and emails. Use returned attachment IDs with
the attachment tools for deeper inspection.

## Request body

- ExtendedSearchNotesRequestSchema
  - `exclude_note_ids` string[] — Note UUIDs to exclude from this result set. Use this to avoid returning notes already inspected by the caller.
  - `filter_by_collection_ids` string[] — Optional collection UUID filters. When provided, results are limited to notes in any listed collection.
  - `filter_by_updated_after` string, date-time, nullable — Optional inclusive lower bound for note update time (ISO 8601). The timestamp must include a timezone offset such as `Z` or `+01:00`.
  - `filter_by_updated_before` string, date-time, nullable — Optional inclusive upper bound for note update time (ISO 8601). The timestamp must include a timezone offset such as `Z` or `+01:00`.
  - `limit` integer — Maximum number of note hits to return. Default is 10; valid range is 1 to 100.
  - `next_page_cursor` string, nullable — Opaque cursor from a previous extended search response. Omit for the first page.
  - `query` string, required — Required text query for searching notes and note-linked attachments. The query must contain at least one non-whitespace character.
  - `sort_by` 'RELEVANCE' | 'DATE'

## Response `200`

OK

- ExtendedSearchNotesResponseSchema
  - `has_next_page` boolean, required — Whether another request can return more matching notes.
  - `next_page_cursor` string, nullable — Opaque cursor for the next page of results.
  - `request_id` string, required — Identifier for this API request. Useful for tracing and support.
  - `results` ExtendedSearchNoteResponseSchema[], required — Matching note results with attachment match context.
    - `attachment_matches` ExtendedSearchAttachmentMatchResponseSchema[] — Matching note-linked attachments. Use `read_attachment` or `answer_question_about_attachment` with `attachment_kind` and `attachment_id` for deeper attachment inspection.
      - `attachment_id` string, uuid, required — UUID of the matching attachment.
      - `attachment_kind` 'pdf' | 'image' | 'audio_recording' | 'calendar_event' | 'email', required
      - `filename` string, nullable — Attachment filename, when available.
      - `highlighted_snippets` string[] — Highlighted attachment snippets relevant to the search query.
      - `importance` number, nullable — Relative importance score for the attachment match, when available.
      - `is_semantic_match` boolean — Whether the match was produced semantically instead of by exact text.
      - `match_source` string, nullable — Search source that produced this attachment match.
      - `matched_entities` string[] — Named entities matched in the attachment, when available.
      - `metadata_json` object — Additional structured match metadata.
      - `ocr_text` string, nullable — Relevant OCR text from an image attachment, when available.
      - `page_number` integer, nullable — One-based page number for PDF matches, when available.
      - `sourcer_kind` string, nullable — Internal source category for the attachment match, when available.
      - `summary` string, nullable — Attachment or page summary, when available.
      - `text_excerpt` string, nullable — Relevant plain-text excerpt from the attachment, when available.
      - `total_pages` integer, nullable — Total page count for PDF matches, when available.
      - `visual_description` string, nullable — Relevant visual description from an image attachment, when available.
    - `created_at` string, date-time, nullable — Creation timestamp for the note in ISO 8601 format.
    - `id` string, uuid, required — UUID of the note.
    - `note_summary` string, nullable — Derived summary of the note, when available.
    - `snippet` string, nullable — Derived preview text for quick display and ranking context.
    - `title` string, required — Current title of the note.
    - `updated_at` string, date-time, nullable — Last modification timestamp for the note in ISO 8601 format.

---

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