ainote Handoffs API

openapi: 3.2.0
info:
  title: ainote MCP — OpenAPI mirror Handoffs API
  version: 1.3.0
  description: OpenAPI 3.1 surface auto-generated from ainote's MCP tool registry. Use this with OpenAI Custom GPT Actions, LangChain remote tools, AutoGen, or any HTTP-first agent runtime that consumes OpenAPI. The native MCP (JSON-RPC) endpoint at POST /api/mcp remains the recommended path for Claude/Cursor/Windsurf. Tool semantics (annotations, idempotency, destructiveness) are identical across both surfaces — see x-mcp-annotations.
  contact:
    name: ainote
    url: https://docs.ainote.dev
  license:
    name: MIT
servers:
- url: https://api.ainote.dev
security:
- McpKeyAuth: []
tags:
- name: handoffs
paths:
  /api/mcp/tools/handoff_save:
    post:
      operationId: tool_handoff_save
      summary: Save a session handoff note for cross-device / cross-session continuation.
      description: Save a session handoff note for cross-device / cross-session continuation. Stored at handoffs/{project}-{topic}-{YYYY-MM-DD}.txt in the user's primary vault. Use the optional `time` param (HHMM, KST) to disambiguate multiple handoffs saved on the same day — it is appended to the topic slug (e.g. topic='phase-d', time='1555' → handoffs/{project}-phase-d-1555-{date}.txt).
      tags:
      - handoffs
      x-mcp-annotations:
        readOnlyHint: false
        destructiveHint: true
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type: string
                  description: Project slug, e.g. 'logi', 'ainote', 'krx_ai'. Lowercase, no spaces.
                topic:
                  type: string
                  description: Short topic slug for this handoff, e.g. 'phase-d-port', 'oauth-fix'. Lowercase-hyphen.
                content:
                  type: string
                  description: 'Full handoff text. Should follow the session-handoff skill template (현재 상태 / 작업 위치 / 수정 파일 / 결정 사항 / 다음 STEP / 알려진 이슈). WAF-bypass tip: prefix the string with ''__B64__:'' followed by base64-encoded payload to bypass Render/Cloudflare edge WAF for large bodies (~10KB+) that get false-positive blocked as SQLi/cmd-injection.'
                content_b64:
                  type: string
                  description: 'Optional: base64-encoded handoff text (use INSTEAD of `content`). For WAF-bypass on large bodies. Server decodes before storing.'
                date:
                  type: string
                  description: Optional override date (YYYY-MM-DD). Defaults to today in server timezone.
                time:
                  type: string
                  description: Optional time-of-day suffix in HHMM 24h format (KST), e.g. '1555'. Appended to the topic slug so multiple handoffs on the same day stay distinguishable. Omit for once-per-day saves.
                device_id:
                  type: string
                  description: 'Optional: client device identifier (e.g., from ~/.claude/ainote-sync/device.id). Stored on FileIndex so future conflict responses can report which device last wrote the handoff. Same field sync_push uses.'
              required:
              - project
              - topic
      responses:
        '200':
          description: Tool executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSuccessResponse'
        '400':
          description: Invalid arguments or business-rule violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolErrorResponse'
        '401':
          description: Missing or invalid McpKey
  /api/mcp/tools/handoff_list:
    post:
      operationId: tool_handoff_list
      summary: List session handoff notes saved in the primary vault under handoffs/…
      description: 'List session handoff notes saved in the primary vault under handoffs/, most-recent first. v2 frontmatter fields (status / has_blockers / tags / task_type) can be filtered server-side and are exposed in each entry without fetching the body. Read-only: entries older than 7 days are filtered out of results (a daily server-side cleanup job permanently deletes them).'
      tags:
      - handoffs
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type: string
                  description: Optional project filter, e.g. 'logi' to list only logi-* handoffs.
                limit:
                  type: integer
                  description: Max entries to return (default 50).
                status:
                  type: string
                  description: 'v2 only: filter by frontmatter status (e.g. ''in_progress'', ''paused'', ''completed'', ''blocked''). v1 handoffs without frontmatter are excluded when this filter is set.'
                has_blockers:
                  type: boolean
                  description: 'v2 only: filter by frontmatter has_blockers (true/false).'
                task_type:
                  type: string
                  description: 'v2 only: filter by frontmatter task_type (e.g. ''feature'', ''bugfix'', ''refactor'', ''research'', ''ops'').'
                tags:
                  type: array
                  items:
                    type: string
                  description: 'v2 only: AND match — entries must contain ALL given tags. Example: [''auth'', ''mobile''].'
                since:
                  type: string
                  description: ISO8601 timestamp — only entries with updated_at >= since are returned.
      responses:
        '200':
          description: Tool executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSuccessResponse'
        '400':
          description: Invalid arguments or business-rule violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolErrorResponse'
        '401':
          description: Missing or invalid McpKey
  /api/mcp/tools/handoff_get:
    post:
      operationId: tool_handoff_get
      summary: Retrieve a session handoff by project + topic.
      description: 'Retrieve a session handoff by project + topic. If date is omitted, returns the most recent matching handoff. Pass `time` (HHMM, KST) to fetch a specific same-day save when multiple exist. Read-only: handoffs older than 7 days are not returned (a daily server-side cleanup job permanently deletes them).'
      tags:
      - handoffs
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type: string
                  description: Project slug used at handoff_save time.
                topic:
                  type: string
                  description: Topic slug used at handoff_save time.
                date:
                  type: string
                  description: Optional YYYY-MM-DD. Omit for latest.
                time:
                  type: string
                  description: Optional HHMM (24h, KST) — same value passed at save time. Required to disambiguate when multiple handoffs share the same project/topic/date.
              required:
              - project
              - topic
      responses:
        '200':
          description: Tool executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSuccessResponse'
        '400':
          description: Invalid arguments or business-rule violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolErrorResponse'
        '401':
          description: Missing or invalid McpKey
components:
  schemas:
    ToolSuccessResponse:
      type: object
      description: 'Successful tool invocation. `content` mirrors the MCP `tools/call` result shape: an array of content blocks (text and optionally a structured resource payload).'
      properties:
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - text
                - resource
              text:
                type: string
    ToolErrorResponse:
      type: object
      description: Uniform error shape emitted by ainote MCP tool handlers.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: JSON-RPC error code (-32xxx range)
            message:
              type: string
          required:
          - code
          - message
  securitySchemes:
    McpKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Send `McpKey <YOUR_MCP_KEY>`. Issue an MCP key at /settings/mcp or via `npx @ainote/mcp signup`.
x-ainote-meta:
  generator: Api::Mcp::OpenapiController
  generated_at: '2026-11-01T14:35:55Z'
  tools_count: 56
  native_mcp_endpoint: https://api.ainote.dev/api/mcp
  agent_compatibility_doc: https://github.com/ainote-dev/ainote-mcp#agent-compatibility