ainote Dev Docs API

openapi: 3.2.0
info:
  title: ainote MCP — OpenAPI mirror Dev Docs 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: dev-docs
paths:
  /api/mcp/tools/list_dev_docs:
    post:
      operationId: tool_list_dev_docs
      summary: List dev documents under the dev/ category hierarchy.
      description: List dev documents under the dev/ category hierarchy. Filter by subcategory (claude, cursor, windsurf, copilot, docs, etc.), search by title, or filter by content type.
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  type: string
                  description: Subcategory filter (claude, cursor, windsurf, copilot, docs, etc.). Omit to list all dev docs.
                search:
                  type: string
                  description: Search keyword in document title
                content_type:
                  type: string
                  enum:
                  - markdown
                  - json
                  - yaml
                  - text
                  description: Filter by content type
      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/get_dev_doc:
    post:
      operationId: tool_get_dev_doc
      summary: Get a single dev document by title or id. Returns full content
      description: Get a single dev document by title or id. Returns full content.
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Document title (e.g., project-a-memory.md)
                id:
                  type: string
                  description: Document UUID
                category:
                  type: string
                  description: Subcategory (claude, cursor, etc.) to disambiguate title
                include_versions:
                  type: boolean
                  description: 'Include version history (default: false)'
      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/create_dev_doc:
    post:
      operationId: tool_create_dev_doc
      summary: Save a document to AI Note cloud for multi-device sync and persistent storage
      description: 'Save a document to AI Note cloud for multi-device sync and persistent storage.


        PRIMARY USE CASES:

        - Memory files: ~/.claude/projects/.../memory/MEMORY.md (AI context that survives device switches)

        - AI config files: CLAUDE.md, .cursorrules, .windsurfrules (not in git, local-only)

        - Local env notes: API keys reference, server credentials (NOT actual secret values)

        - Project notes: architecture decisions, dev diaries, planning docs


        MULTI-DEVICE WORKFLOW:

        Laptop → push: create_dev_doc(title, content, local_path="~/.claude/.../MEMORY.md")

        Desktop → pull: pull_dev_docs() → automatically writes files to their local paths


        CATEGORIES (subcategories under dev/):

        - memory: Claude/AI memory files (~/.claude/projects/.../memory/)

        - claude: CLAUDE.md files and Claude-specific configs

        - cursor: .cursorrules files

        - env: environment notes and config references

        - docs: general project documentation


        Set local_path to enable pull_dev_docs auto-sync to this machine.'
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: false
        destructiveHint: false
        idempotentHint: false
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Filename as title (e.g., ainote-memory.md, project-claude.md)
                content:
                  type: string
                  description: Full file content (markdown, json, yaml, text)
                category:
                  type: string
                  description: 'Subcategory: memory | claude | cursor | env | docs | custom. Default: docs'
                content_type:
                  type: string
                  enum:
                  - markdown
                  - json
                  - yaml
                  - text
                  description: Content type. Auto-detected from title extension if omitted.
                local_path:
                  type: string
                  description: Absolute path on this machine (e.g., ~/.claude/projects/-Users-seunghan/memory/MEMORY.md). Used by pull_dev_docs to restore file on other devices. Supports ~ expansion.
                memory_type:
                  type: string
                  enum:
                  - state
                  - event
                  - preference
                  description: 'Memory update semantics: ''state'' = latest value replaces the past (used by memory_search latest_state mode), ''event'' = immutable accumulating log, ''preference'' = user preference. Omit for plain documents.'
              required:
              - title
              - content
      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/update_dev_doc:
    post:
      operationId: tool_update_dev_doc
      summary: Update an existing dev document.
      description: Update an existing dev document. Supports replace (default), append, or prepend modes. Optionally update the local_path for sync.
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: false
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Document title
                id:
                  type: string
                  description: Document UUID
                category:
                  type: string
                  description: Subcategory to disambiguate title
                content:
                  type: string
                  description: New content
                mode:
                  type: string
                  enum:
                  - replace
                  - append
                  - prepend
                  description: 'Update mode (default: replace)'
                local_path:
                  type: string
                  description: Update the local file path for multi-device sync
                memory_type:
                  type: string
                  enum:
                  - state
                  - event
                  - preference
                  description: Set the memory update semantics (state | event | preference). Pass null/empty to clear.
              required:
              - content
      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/pull_dev_docs:
    post:
      operationId: tool_pull_dev_docs
      summary: Restore all synced files to this device.
      description: 'Restore all synced files to this device. Fetches every dev doc that has a local_path set and writes the content to that path on disk.


        WHEN TO USE:

        - First time setup on a new machine (desktop, laptop, etc.)

        - After reinstalling macOS or setting up a fresh environment

        - To restore Claude memory files, CLAUDE.md configs, and other local-only files


        WHAT IT DOES:

        1. Fetches all your dev docs that have local_path set

        2. Creates any missing parent directories automatically

        3. Writes the file content to each local_path on THIS machine

        4. Reports success/failure for each file


        TYPICAL FILES RESTORED:

        - ~/.claude/projects/.../memory/MEMORY.md (AI context memory)

        - ~/projects/*/CLAUDE.md (project-specific AI instructions)

        - .cursorrules, .windsurfrules (editor AI configs)


        Run this once after setting up ainote MCP on a new device.'
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  type: string
                  description: Subcategory filter. Omit to pull all docs with local_path.
      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/delete_dev_doc:
    post:
      operationId: tool_delete_dev_doc
      summary: Soft-delete a dev document by title or UUID. Reversible from trash.
      description: Soft-delete a dev document by title or UUID. Reversible from trash. Pass `category` when multiple docs share the same title across subcategories (memory/claude/cursor/env/docs).
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: false
        destructiveHint: true
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Document title
                id:
                  type: string
                  description: Document UUID
                category:
                  type: string
                  description: Subcategory to disambiguate title
      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/list_dev_categories:
    post:
      operationId: tool_list_dev_categories
      summary: List all subcategories under dev/ (memory, claude, cursor, env, docs, mcp…
      description: List all subcategories under dev/ (memory, claude, cursor, env, docs, mcp, custom...) with document counts. Use to discover which categories exist before calling list_dev_docs with a category filter.
      tags:
      - dev-docs
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      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