几分钟内把外部上下文送进 MyInc 工作区。

{
  "title": "保存的回答",
  "text": "这是值得留存的最终摘要。",
  "tags": ["research", "launch"]
}

{
  "success": true,
  "data": {
    "id": "clip_123",
    "title": "保存的回答",
    "text": "这是值得留存的最终摘要。"
  },
  "error": null
}

• 适合作为 Hermes 或自有 agent 接入的第一个端点。
• 一次保存一条好回答时最为简单。
• GET /api/agent/clips 使用 clips:read 列出 clips。

{
  "items": [
    { "type": "url", "url": "https://example.com/article" },
    { "type": "markdown", "title": "笔记", "text": "# 要点\n- 一\n- 二" }
  ]
}

{
  "success": true,
  "data": {
    "captureBatchId": "batch_123",
    "created": [
      { "id": "clip_1", "title": "https://example.com/article", "url": "https://example.com/article" },
      { "id": "clip_2", "title": "笔记", "url": null }
    ],
    "failed": []
  },
  "error": null
}

• 当 agent 一次发送多个条目时最合适。
• 一个请求中同时支持 text、url 和 markdown（最多 50 条）。
• 该路由按条目扣除 AI 额度，额度不足时返回条目级别的 failed。

curl https://myinc.app/api/agent/upload \
  -H 'Authorization: Bearer tk_your_api_key' \
  -H 'Idempotency-Key: upload-001' \
  -F '[email protected]'

{
  "success": true,
  "data": {
    "id": "clip_upload_123",
    "title": "notes.md"
  },
  "error": null
}

• 当 agent 发送真实文件而非纯 JSON 时使用此路由。
• scoped key 与 idempotency 同样适用于上传。
• 这是 MyInc 文件上传的公开 agent 外观，而非内部 web 路由。

{
  "mode": "custom",
  "prompt": "把这个 page 变成一篇可发布的简短简报。"
}

{
  "success": true,
  "data": {
    "jobId": "draft_123",
    "type": "page_generation",
    "status": "completed",
    "result": {
      "draftId": "draft_123"
    }
  },
  "error": null
}

• 生成的 draft 会在 MyInc 中保持待你批准状态，不会自动发布。
• 请先把 clips 整理成 page 再调用（POST /api/agent/pages、GET /api/agent/pages/:id）。
• 用 GET /api/agent/jobs/:id 查询 draft 状态；生成消耗与应用内相同的 AI 额度。

{
  "name": "四月发布计划",
  "template": "goal_milestones",
  "icon": "🚀"
}

{
  "success": true,
  "data": {
    "id": "project_123",
    "name": "四月发布计划",
    "template": "goal_milestones"
  },
  "error": null
}

• 当 agent 需要长期工作区而不只是单个 clip 时使用。
• 模板：goal_milestones 或 pipeline_board。
• 创建 project 遵循与主应用相同的活跃项目数上限。

{
  "stage": "clip",
  "referenceId": "clip_123"
}

{
  "success": true,
  "data": {
    "id": "project_item_123",
    "stage": "clip",
    "referenceId": "clip_123"
  },
  "error": null
}

• 若省略 columnId，MyInc 会解析该 stage 的第一个 workflow column。
• 在创建 clip 或 page 后立即衔接 project 流程最为自然。