monologue-notes-api

Monologue Notes API

此技能提供直接调用 Monologue Notes REST API 所需的信息。 用于对经过身份验证的用户的笔记执行只读操作。

请根据任务选择合适的 HTTP 客户端：curl、短脚本或其他支持 REST 的工具。 除非用户要求，否则不要臆造客户端库。

身份验证

使用环境变量 MONOLOGUE_API_KEY 作为 bearer 令牌。

• 必需的身份验证标头：Authorization: Bearer $MONOLOGUE_API_KEY
• 必需的作用域：notes:read
• 切勿打印、回显或记录令牌，也不要在回复用户时包含令牌
• 只能通过 shell 变量展开，将令牌传入 Authorization 标头

检查令牌是否可用，但不要显示令牌：

if [ -z "${MONOLOGUE_API_KEY:-}" ]; then
  echo "MONOLOGUE_API_KEY is not set"
fi

如果缺少 MONOLOGUE_API_KEY：

• 告知用户该环境变量不存在
• 询问用户是否愿意提供 API 密钥
• 在令牌可用之前，不要尝试调用需要身份验证的 API

避免使用以下命令，因为它们会泄露机密：

echo "$MONOLOGUE_API_KEY"
env | grep MONOLOGUE_API_KEY
set | grep MONOLOGUE_API_KEY

基础 URL

• 基础 URL：https://api.monologue.to
• API 类型：只读 Notes API
• 数据格式：JSON
• 时间戳：ISO 8601 日期时间字符串

请求模式

所有请求均使用以下模式：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/..."

如果需要结构化输出，可将响应通过管道传给 jq。

端点

列出笔记

GET /v1/public-api/notes

返回经过身份验证的用户的一页笔记。

支持的查询参数：

• limit：介于 1 和 100 之间的整数，默认值为 20
• cursor：来自之前响应的不透明分页游标
• created_after：ISO 8601 时间戳
• created_before：ISO 8601 时间戳
• updated_after：ISO 8601 时间戳
• q：针对标题、摘要和转录内容的全文搜索

示例：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?limit=20&q=interview"

使用 jq 的示例：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?limit=20" \
  | jq '{next_cursor, items: [.items[] | {note_id, title, summary, created_at, updated_at}]}'

预期的响应字段：

• items：笔记摘要数组
• next_cursor：下一页的游标（如果有）

每个列表项可能包含：

• note_id
• title
• summary
• created_at
• updated_at

可能的错误：

• 400：筛选条件或游标无效
• 401：缺少令牌或令牌无效
• 403：令牌缺少必需的作用域
• 422：验证错误

获取单条笔记

GET /v1/public-api/notes/{note_id}

返回一条属于经过身份验证的用户的笔记的完整详情。

路径参数：

• note_id：列表端点返回的笔记标识符

示例：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes/NOTE_ID"

使用 jq 的示例：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes/NOTE_ID" \
  | jq '{note_id, title, summary, transcript, transcript_segments, created_at, updated_at}'

除了列表字段外，完整笔记响应还可能包含：

• transcript
• transcript_segments

注意：

• transcript_segments 是类型不严格的结构化 JSON，可能为 null
• 404 表示未找到属于经过身份验证的用户的该笔记

可能的错误：

• 401：缺少令牌或令牌无效
• 403：令牌缺少必需的作用域
• 404：未找到笔记
• 422：验证错误

常见工作流

按关键词搜索笔记

使用 q 参数：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?q=meeting"

搜索范围包括：

• 笔记标题
• 笔记摘要
• 笔记转录内容

分页浏览结果

1. 调用 GET /v1/public-api/notes
2. 从响应中读取 next_cursor
3. 将该游标作为 cursor 查询参数传回
4. 当 next_cursor 缺失或为 null 时停止

示例：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?limit=50&cursor=OPAQUE_CURSOR"

按时间筛选

使用 ISO 8601 日期时间值：

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?created_after=2026-01-01T00:00:00Z"

操作规则

• 将此 API 视为只读
• 不要声称支持写入；此技能仅涵盖列出和读取笔记
• 请求时优先使用 https://api.monologue.to
• 报告失败时，概述 HTTP 状态和相关响应正文，不要泄露令牌
• 如果用户要求的工作流需要在本地进行后处理，请先获取数据，再单独进行转换

来源说明

此技能基于：

• /Users/eleanor/repos/obsidian/intellectronica/2026-04-21-20-10 Monologue API.md
• 2026-04-22 针对 https://api.monologue.to/public-openapi.json 进行的实时 OpenAPI 检查