{"openapi": "3.1.0", "info": {"title": "Nibvine Integrations API", "version": "1.0.0", "description": "External AI integration surface for Nibvine, including remote MCP, scoped access tokens, and connect preset generation."}, "servers": [{"url": "https://nibvine.com"}], "components": {"securitySchemes": {"BearerToken": {"type": "http", "scheme": "bearer", "description": "Use a scoped Nibvine external access token or a DRF auth token."}}}, "x-nibvine-scopes": [{"scope": "mcp:connect", "label": "Connect via MCP"}, {"scope": "projects:read", "label": "Read projects"}, {"scope": "projects:write", "label": "Write/update project metadata with preview/commit"}, {"scope": "notes:read", "label": "Read notes"}, {"scope": "notes:write", "label": "Write notes with preview/commit"}, {"scope": "tasks:read", "label": "Read tasks"}, {"scope": "tasks:write", "label": "Write tasks with preview/commit"}, {"scope": "changes:read", "label": "Read project changes"}, {"scope": "ideas:read", "label": "Read ideas"}, {"scope": "ideas:write", "label": "Write ideas with preview/commit"}, {"scope": "comments:read", "label": "Read comments and AI chat threads"}, {"scope": "comments:write", "label": "Write comments with preview/commit"}, {"scope": "quicknotes:read", "label": "Read quick notes"}, {"scope": "quicknotes:write", "label": "Create quick notes with preview/commit"}, {"scope": "members:read", "label": "Read project members and invite links"}, {"scope": "members:write", "label": "Manage members and invite links with preview/commit"}, {"scope": "analyses:read", "label": "Read stored AI analyses"}], "x-nibvine-scope-bundles": {"read_only": {"label": "Read-only", "description": "Safe default for external AI tools. Can read everything in a project \u2014 context, notes, tasks, ideas, comments, quick notes, members, AI analyses, and change history \u2014 and change nothing.", "scopes": ["mcp:connect", "projects:read", "notes:read", "tasks:read", "changes:read", "ideas:read", "comments:read", "quicknotes:read", "members:read", "analyses:read"]}, "safe_write": {"label": "Safe writes", "description": "Adds preview-and-commit mutation flows across the whole product surface (projects, notes, tasks, ideas, comments, quick notes, members) without giving raw unrestricted writes.", "scopes": ["mcp:connect", "projects:read", "notes:read", "tasks:read", "changes:read", "ideas:read", "comments:read", "quicknotes:read", "members:read", "analyses:read", "projects:write", "notes:write", "tasks:write", "ideas:write", "comments:write", "quicknotes:write", "members:write"]}}, "paths": {"/mcp": {"post": {"summary": "Remote MCP endpoint", "description": "Supports initialize, notifications/initialized, ping, tools/list, and tools/call. Exposes 55 tools covering projects, notes, tasks, ideas, comments, quick notes, members, invite links, AI analyses, and change history. Every mutation goes through a preview_* tool followed by commit_write_action (or cancel_write_action).", "security": [{"BearerToken": []}], "x-mcp-protocol-version": "2025-06-18", "x-mcp-tools": [{"name": "list_projects", "description": "List all projects you have access to. Returns id, title, category, priority, and note/task/idea counts. Use this to discover project IDs before calling other tools.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "get_project", "description": "Read full project metadata: vision, goal, description, tech_stack, target_audience, success_metrics, constraints, completion_percentage. Use this when you need to inspect or update specific project fields. For AI-optimized context with notes and tasks, use get_context_pack instead.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "get_project_context", "description": "Read project metadata + 5 latest notes + 5 latest changes in one call. Lightweight alternative to get_context_pack when you don't need profile-based ranking. Prefer get_context_pack(profile=...) for curated, role-specific context.", "required_scopes": ["mcp:connect", "projects:read", "notes:read", "changes:read"], "mutating": false}, {"name": "get_context_pack", "description": "Get AI-optimized context pack with notes and tasks ranked by relevance to a role profile. Profiles: 'coding' (architecture, APIs, bugs), 'founder' (vision, priorities, market), 'product' (UX, roadmap, feedback), 'marketing' (positioning, messaging), 'fundraising' (traction, metrics), 'support' (recent issues). Returns structured data + pre-rendered exports (markdown, llm_document, compact_summary).", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "get_note", "description": "Read a single note's full content by note_id. Use when you need the complete text of a specific note. To browse notes hierarchically, use get_note_tree. To search by keyword, use search_notes.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "search_notes", "description": "Full-text search across note titles and content. Returns matching notes with snippets. Use get_note_tree for hierarchical browsing instead, or get_context_pack for curated AI context.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "get_note_tree", "description": "Get hierarchical note tree (parent-child structure) for a project. Shows note titles, types, tags, and nesting. Use this to understand how notes are organized or to find parent_note_id for creating child notes. Use search_notes to find notes by keyword instead.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "get_recent_changes", "description": "Read project change log: who changed what, when, and from which source (user, AI, system). Use this to see recent activity and audit trail.", "required_scopes": ["mcp:connect", "changes:read"], "mutating": false}, {"name": "get_changes_since", "description": "Get all changes to a project since a timestamp. Returns change log entries, modified notes, modified tasks, and counts. Use this for incremental sync: pass the last_synced_at from .nibvine.json to see what changed remotely.", "required_scopes": ["mcp:connect", "changes:read"], "mutating": false}, {"name": "get_sync_status", "description": "Compare local sync state with remote to detect drift. Pass local_context_version and local_updated_at from .nibvine.json. Returns whether sync is needed, how many versions behind, active project members, and task/note counts. Use this before syncing to decide what to do.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "list_tasks", "description": "List project tasks, optionally filtered by status. Returns title, description, status, priority, due_date. Use get_task(task_id) to read a single task in detail.", "required_scopes": ["mcp:connect", "tasks:read"], "mutating": false}, {"name": "get_task", "description": "Read a single task's full details by task_id. Use list_tasks(project_id) first to find task IDs.", "required_scopes": ["mcp:connect", "tasks:read"], "mutating": false}, {"name": "get_claude_instructions", "description": "START HERE: Get complete workflow guide for this Nibvine project. Returns current project state, available tools, data types, best practices, and step-by-step instructions. Call this first in every new session.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "get_public_settings", "description": "Read the public sharing settings for a project: is_public toggle, which content is shared (notes, tasks, ideas, analyses), published note branches, and the public URL. Use before updating sharing settings.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "update_public_settings", "description": "Update public sharing settings for a project. Toggle is_public to enable/disable the public page. Choose what to share: notes, tasks, ideas, analyses. Set published_note_ids to select which root-level note branches appear on the public page. Set regenerate_token=true to invalidate old share links. Changes apply immediately (no preview/commit needed).", "required_scopes": ["mcp:connect", "projects:write"], "mutating": true}, {"name": "preview_create_project", "description": "Preview creating a new Nibvine project. Returns a write_action_id \u2014 review the preview, then call commit_write_action to execute. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "projects:write"], "mutating": true}, {"name": "preview_update_project", "description": "Preview updating project metadata. Pass only the fields you want to change. Returns a write_action_id \u2014 review, then commit. Preview expires in 30 minutes. Call get_project first to see current values.", "required_scopes": ["mcp:connect", "projects:write"], "mutating": true}, {"name": "preview_create_note", "description": "Preview creating a new note. Set parent_note_id to nest under an existing note (use get_note_tree to find IDs). Returns write_action_id \u2014 review, then commit. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "preview_update_note", "description": "Preview updating an existing note. Pass only the fields you want to change. Call get_note(note_id) first to see current content. Returns write_action_id \u2014 review, then commit. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "preview_create_task", "description": "Preview creating a new task. Returns write_action_id \u2014 review, then commit. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "tasks:write"], "mutating": true}, {"name": "preview_update_task", "description": "Preview updating an existing task. Pass only changed fields. Call get_task(task_id) or list_tasks(project_id) to find task IDs. Returns write_action_id \u2014 review, then commit. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "tasks:write"], "mutating": true}, {"name": "preview_delete_note", "description": "Preview deleting a note. By default cascades (deletes children too). Set cascade=false to reparent children to the deleted note's parent. Returns write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "list_notes_by_tag", "description": "List notes in a project that contain a given tag. Returns note summaries.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "batch_tag_notes", "description": "Add or remove tags from multiple notes at once. Provide note_ids and at least one of add_tags or remove_tags.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "list_ideas", "description": "List a project's ideas (the lightweight idea inbox that sits next to notes and tasks). Optionally filter by implementation state or a text query. Use get_idea(idea_id) for the full body.", "required_scopes": ["mcp:connect", "ideas:read"], "mutating": false}, {"name": "get_idea", "description": "Read a single idea in full by idea_id. Call list_ideas(project_id) first to discover idea IDs.", "required_scopes": ["mcp:connect", "ideas:read"], "mutating": false}, {"name": "list_comments", "description": "List the project's unified comment stream (human messages, AI assistant replies, and system events), newest first. Filter by note_id to read one note's discussion, by role, or set root_only=true to skip replies.", "required_scopes": ["mcp:connect", "comments:read"], "mutating": false}, {"name": "get_comment_thread", "description": "Read one full comment thread: walks up to the root comment and returns it with all nested replies. Pass any comment_id in the thread.", "required_scopes": ["mcp:connect", "comments:read"], "mutating": false}, {"name": "list_quick_notes", "description": "List your quick notes \u2014 free-form captures waiting for AI placement in the note tree (draft, analyzing, ready_for_review, confirmed, saved, cancelled). Project-scoped tokens only ever see quick notes tied to their project.", "required_scopes": ["mcp:connect", "quicknotes:read"], "mutating": false}, {"name": "get_quick_note", "description": "Read one quick note with its full AI placement analysis: general summary, branch analysis, detailed analysis, placement strategy, and confidence score.", "required_scopes": ["mcp:connect", "quicknotes:read"], "mutating": false}, {"name": "list_project_members", "description": "List everyone with access to a project: the owner plus each membership, with username, role, active flag, and join date. Use before removing a member or issuing an invite link.", "required_scopes": ["mcp:connect", "members:read"], "mutating": false}, {"name": "list_invite_links", "description": "List the project's one-time invite links with their tokens, paths, and consumption state. Owner-only. Use preview_create_invite_link to mint a new one.", "required_scopes": ["mcp:connect", "members:read"], "mutating": false}, {"name": "list_tags", "description": "List every tag used on a project's notes with how many notes carry it, ordered by frequency. Use this to discover the project's tag vocabulary before tagging or calling list_notes_by_tag.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "get_note_path", "description": "Get the breadcrumb from the project root down to a note: every ancestor in order plus a human-readable 'A / B / C' string. Use it to explain where a note lives before moving or updating it.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "get_note_children", "description": "List the direct children of a note in sibling order, with each child's own children count. Cheaper than get_note_tree when you only need to walk one level at a time.", "required_scopes": ["mcp:connect", "notes:read"], "mutating": false}, {"name": "list_ai_analyses", "description": "List stored AI analyses for a project (presentation, audience, strategy) with token usage and cost. Set include_content=true to get the full analysis body and prompt instead of a 500-character preview.", "required_scopes": ["mcp:connect", "analyses:read"], "mutating": false}, {"name": "get_project_stats", "description": "Get counts and health metrics for a project in one call: notes by type/relation/depth, tasks by status and priority, ideas, comments, analyses, members, change count, and last activity timestamps. Use it to report progress without pulling content.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "export_project", "description": "Export the whole project as one JSON document: metadata, flat notes, the note tree, tasks, ideas, comments, AI analyses, public settings, and change log. Sections your token cannot read are skipped and named in omitted_sections. Use for backups, migrations, or loading everything into another tool.", "required_scopes": ["mcp:connect", "projects:read"], "mutating": false}, {"name": "list_write_actions", "description": "List write actions created with this token \u2014 by default the pending previews that are still waiting for commit_write_action. Pass status='all' to include committed, expired, and canceled ones. Use it to recover a write_action_id you lost.", "required_scopes": ["mcp:connect"], "mutating": false}, {"name": "whoami", "description": "Report the identity behind this connection: the Nibvine user, whether the credential is a scoped external token or a user token, its scopes, its project binding (if any), the accessible project IDs, and exactly which tools your scopes allow or block. Call this when a tool fails with a scope error.", "required_scopes": ["mcp:connect"], "mutating": false}, {"name": "preview_delete_task", "description": "Preview deleting a task. Returns a write_action_id \u2014 review the preview, then call commit_write_action. Deletion is permanent; prefer preview_update_task(status='done') to close work you want to keep. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "tasks:write"], "mutating": true}, {"name": "preview_delete_project", "description": "Preview deleting an entire project with all of its notes, tasks, ideas, comments, analyses, and history. Owner-only and irreversible: confirm_title must exactly match the project's current title. Returns a write_action_id \u2014 review the counts in the preview, then call commit_write_action.", "required_scopes": ["mcp:connect", "projects:write"], "mutating": true}, {"name": "preview_move_note", "description": "Preview re-parenting a note (with its whole subtree) and/or repositioning it among its siblings. Pass new_parent_note_id=null to move it to the project root; omit it to keep the current parent and only change position. position is the zero-based index among the target siblings; omit to append last. Depth and order of every descendant are recomputed on commit.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "preview_reorder_notes", "description": "Preview reordering a sibling group. note_ids is the new front-to-back order and must contain direct children of parent_note_id (omit parent_note_id to reorder the project's root notes). Siblings you leave out keep their relative order after the listed ones. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "preview_create_idea", "description": "Preview adding an idea to a project's idea list. Ideas are flat, lightweight sparks \u2014 use notes for structured knowledge and tasks for work items. Returns a write_action_id \u2014 review, then commit. Preview expires in 30 minutes.", "required_scopes": ["mcp:connect", "ideas:write"], "mutating": true}, {"name": "preview_update_idea", "description": "Preview updating an idea. Pass only the fields you want to change \u2014 typically is_implemented=true once the idea ships. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "ideas:write"], "mutating": true}, {"name": "preview_delete_idea", "description": "Preview deleting an idea permanently. Returns a write_action_id \u2014 review, then commit. Consider preview_update_idea(is_implemented=true) instead when the idea was simply completed.", "required_scopes": ["mcp:connect", "ideas:write"], "mutating": true}, {"name": "preview_create_comment", "description": "Preview posting a comment into the project's chat stream. Attach it to a note with note_id, or reply inside a thread with parent_comment_id. role defaults to 'assistant' \u2014 the correct role for messages an AI agent writes; use 'user' only when relaying something the human said. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "comments:write"], "mutating": true}, {"name": "preview_create_quick_note", "description": "Preview capturing a quick note \u2014 free-form text parked for later placement in the note tree, exactly like the web quick-capture box. Optionally suggest a parent note. Use this when you have a thought worth keeping but no clear home yet; use preview_create_note when you know where it belongs. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "quicknotes:write"], "mutating": true}, {"name": "preview_import_notes", "description": "Preview importing a whole note subtree in one call. notes is a nested array where each node may carry its own children array, so a full branch (parents and descendants) is created by a single commit. Attach it under parent_note_id or omit that for new root branches. Limits: 200 notes and 10 levels per import. Returns a write_action_id whose preview contains the outline \u2014 review, then commit.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "preview_batch_create_notes", "description": "Preview creating up to 100 notes in one write action. Each entry is flat and may name an existing parent_note_id; parents created in the same batch are NOT addressable \u2014 use preview_import_notes for a new hierarchy. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "notes:write"], "mutating": true}, {"name": "preview_create_invite_link", "description": "Preview minting a new one-time invite link that lets another person join the project as a member. Owner-only. The committed result contains the token and the shareable URL. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "members:write"], "mutating": true}, {"name": "preview_remove_member", "description": "Preview revoking a member's access to a project by deactivating their membership. Owner-only; the owner cannot be removed. Identify the member by username or user_id from list_project_members. Returns a write_action_id \u2014 review, then commit.", "required_scopes": ["mcp:connect", "members:write"], "mutating": true}, {"name": "cancel_write_action", "description": "Discard a pending write action so it can never be committed. Use it when the preview is wrong or the user declines. Already-committed actions cannot be canceled; expired previews simply become uncommittable on their own.", "required_scopes": ["mcp:connect"], "mutating": true}, {"name": "commit_write_action", "description": "Execute a previously previewed write action. Call this after reviewing the preview from any preview_* tool. The write_action_id comes from the preview response. Previews expire after 30 minutes \u2014 if expired, create a new preview.", "required_scopes": ["mcp:connect"], "mutating": true}]}}, "/.well-known/nibvine-ai.json": {"get": {"summary": "AI integration manifest with the MCP tool and scope catalogue"}}, "/api/integrations/connect-presets/": {"get": {"summary": "List supported clients, access modes, and token lifetime presets", "security": [{"BearerToken": []}]}}, "/api/integrations/connect-presets/generate/": {"post": {"summary": "Generate a ready-to-paste preset for an AI client", "security": [{"BearerToken": []}]}}, "/api/integrations/access-tokens/": {"get": {"summary": "List scoped external access tokens", "security": [{"BearerToken": []}]}, "post": {"summary": "Create a scoped external access token", "security": [{"BearerToken": []}]}}, "/api/integrations/access-tokens/{id}/": {"patch": {"summary": "Update or revoke a scoped external access token", "security": [{"BearerToken": []}]}}, "/api/integrations/write-actions/": {"get": {"summary": "List previewed or committed external write actions", "security": [{"BearerToken": []}]}}, "/api/integrations/write-actions/preview/": {"post": {"summary": "Create a safe write preview for a note or task mutation", "security": [{"BearerToken": []}]}}, "/api/integrations/write-actions/{id}/commit/": {"post": {"summary": "Commit a previously previewed external write action", "security": [{"BearerToken": []}]}}, "/api/projects/{id}/context-pack/": {"get": {"summary": "Get a high-level project context pack with optional role profile", "security": [{"BearerToken": []}]}}, "/api/projects/{id}/recent-changes/": {"get": {"summary": "Get the recent project activity feed with pending external write previews", "security": [{"BearerToken": []}]}}, "/api/projects/{id}/activity/": {"get": {"summary": "Alias for the recent project activity feed", "security": [{"BearerToken": []}]}}}}