Skip to content

REST API reference

This page is generated from the server's own URL map, so all 190 endpoints below are what the running service actually serves.

Authentication

Every endpoint except the discovery documents needs a credential. Two are accepted, and both go in the Authorization header.

Two accepted credentials
# Scoped token, created on the connect page. Preferred for agents.
Authorization: Bearer nbv_xxxxxxxxxxxxxxxxxxxx

# Standard account token from POST /api/auth/token/
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
  • A scoped token only reaches the scopes you granted it, and a project-scoped token filters every query to that one project.
  • An account token has the same reach as the signed-in user.
  • Browser sessions also authenticate, which is what the in-app fetches use.

Conventions

  • Requests and responses are JSON. Send Content-Type: application/json on writes.
  • List endpoints are paginated with page and page_size, and return count, next, previous and results.
  • Most lists accept search and ordering, and lists that belong to a project accept a project filter.
  • You only ever see projects you own or are an active member of. Anything else answers 404 rather than 403, so the API never confirms that a record exists.
  • Errors return a JSON body with a detail field and the matching status code.
  • A machine-readable OpenAPI 3.1 schema for this whole API is served at /openapi/nibvine.json, and the integration subset at /openapi/integrations.json.

Projects

GET /api/projects/ List the records you can see.
POST /api/projects/ Create a new record.
GET /api/projects/{pk}/ Fetch a single record.
PUT /api/projects/{pk}/ Replace a record.
PATCH /api/projects/{pk}/ Update part of a record.
DELETE /api/projects/{pk}/ Delete a record.
POST /api/projects/{pk}/archive/ Mark the project as archived.
GET /api/projects/{pk}/changes/ Change-log entries for the project, newest first.
POST /api/projects/{pk}/duplicate/ Deep-copy the project, optionally including notes, tasks and ideas.
GET /api/projects/{pk}/export/ Complete JSON export of the project, its note tree, tasks and ideas.
GET /api/projects/{pk}/invites/ List or mint one-time invite links (owner only).
POST /api/projects/{pk}/invites/ List or mint one-time invite links (owner only).
GET /api/projects/{pk}/members/ List project members, or add one by ``user_id``/``username``/``email``.
POST /api/projects/{pk}/members/ List project members, or add one by ``user_id``/``username``/``email``.
DELETE /api/projects/{pk}/members/{user_id}/ Remove one member from the project (owner only).
GET /api/projects/{pk}/note-tree/ Full nested note tree (alias of ``tree`` that is never shadowed).
GET /api/projects/{pk}/public-settings/ Read or update the public sharing settings for the project.
PUT /api/projects/{pk}/public-settings/ Read or update the public sharing settings for the project.
PATCH /api/projects/{pk}/public-settings/ Read or update the public sharing settings for the project.
POST /api/projects/{pk}/public-settings/regenerate-token/ Roll the public share token, invalidating the old public URL.
GET /api/projects/{pk}/stats/ Counts and completion metrics for one project.
POST /api/projects/{pk}/unarchive/ Restore an archived project.
GET /api/projects/{project_id}/activity/
GET /api/projects/{project_id}/context-pack/
GET /api/projects/{project_id}/recent-changes/

Notes

GET /api/notes/ List the records you can see.
POST /api/notes/ Create a new record.
GET /api/notes/tags/ Distinct tags with usage counts, optionally scoped by ``?project=``.
GET /api/notes/{pk}/ Fetch a single record.
PUT /api/notes/{pk}/ Replace a record.
PATCH /api/notes/{pk}/ Update part of a record.
DELETE /api/notes/{pk}/ Delete a record.
GET /api/notes/{pk}/branch/ The note plus its entire subtree, nested under ``children``.
GET /api/notes/{pk}/children/ Direct children of the note, in tree order.
POST /api/notes/{pk}/move/ Re-parent and/or re-order the note, keeping depth/order consistent.

Tasks

GET /api/tasks/ List the records you can see.
POST /api/tasks/ Create a new record.
GET /api/tasks/{pk}/ Fetch a single record.
PUT /api/tasks/{pk}/ Replace a record.
PATCH /api/tasks/{pk}/ Update part of a record.
DELETE /api/tasks/{pk}/ Delete a record.
POST /api/tasks/{pk}/toggle/ Flip ``is_completed`` and keep ``status`` in sync.

Ideas

GET /api/ideas/ List the records you can see.
POST /api/ideas/ Create a new record.
GET /api/ideas/{pk}/ Fetch a single record.
PUT /api/ideas/{pk}/ Replace a record.
PATCH /api/ideas/{pk}/ Update part of a record.
DELETE /api/ideas/{pk}/ Delete a record.
POST /api/ideas/{pk}/implement/ Mark the idea implemented (send ``{"is_implemented": false}`` to undo).

Comments

GET /api/comments/ List the records you can see.
POST /api/comments/ Create a new record.
GET /api/comments/{pk}/ Fetch a single record.
PUT /api/comments/{pk}/ Replace a record.
PATCH /api/comments/{pk}/ Update part of a record.
DELETE /api/comments/{pk}/ Delete a record.
GET /api/comments/{pk}/thread/ The comment plus every reply beneath it, oldest first.

Quick notes

GET /api/quick-notes/ List the records you can see.
POST /api/quick-notes/ Create a new record.
GET /api/quick-notes/analyze/ API endpoint to trigger analysis (for AJAX requests)
GET /api/quick-notes/{pk}/ Fetch a single record.
PUT /api/quick-notes/{pk}/ Replace a record.
PATCH /api/quick-notes/{pk}/ Update part of a record.
DELETE /api/quick-notes/{pk}/ Delete a record.

AI analyses

GET /api/ai-analyses/ List the records you can see.
POST /api/ai-analyses/ Create a new record.
GET /api/ai-analyses/{pk}/ Fetch a single record.
PUT /api/ai-analyses/{pk}/ Replace a record.
PATCH /api/ai-analyses/{pk}/ Update part of a record.
DELETE /api/ai-analyses/{pk}/ Delete a record.

Change history

GET /api/project-changes/ List the records you can see.
GET /api/project-changes/{pk}/ Fetch a single record.

Members

GET /api/project-members/ List the records you can see.
POST /api/project-members/ Create a new record.
GET /api/project-members/{pk}/ Fetch a single record.
PUT /api/project-members/{pk}/ Replace a record.
PATCH /api/project-members/{pk}/ Update part of a record.
DELETE /api/project-members/{pk}/ Delete a record.

Invites

GET /api/project-invites/ List the records you can see.
POST /api/project-invites/ Create a new record.
GET /api/project-invites/{pk}/ Fetch a single record.
DELETE /api/project-invites/{pk}/ Delete a record.
POST /api/project-invites/{pk}/revoke/ Deactivate an invite link without deleting the audit record.

Public sharing

GET /api/project-public-settings/ List the records you can see.
GET /api/project-public-settings/{pk}/ Fetch a single record.
PUT /api/project-public-settings/{pk}/ Replace a record.
PATCH /api/project-public-settings/{pk}/ Update part of a record.
POST /api/project-public-settings/{pk}/regenerate-token/ Roll the public share token for this project.

Note tree

GET /api/projects/{pk}/tree/ Full nested note tree for the project.
GET /api/projects/{project_id}/tree/ Get complete tree view for a project
POST /api/projects/{project_id}/tree/batch/ Batch create multiple notes
GET /api/projects/{project_id}/tree/depth/{depth}/ Get all notes at a specific depth level
GET /api/projects/{project_id}/tree/export/ Export entire tree as JSON
POST /api/projects/{project_id}/tree/import/ Import notes from JSON structure
POST /api/projects/{project_id}/tree/notes/ Create new note in tree with position
GET /api/projects/{project_id}/tree/path/{note_id}/ Get the path from root to a specific note
POST /api/projects/{project_id}/tree/reorder/ Reorder notes in tree - handle drag and drop
GET /api/projects/{project_id}/tree/search/ Search notes in project tree
GET /api/projects/{project_id}/tree/statistics/ Get detailed statistics about project tree
POST /api/projects/{project_id}/tree/tags/batch/ Update tags for multiple notes
POST /api/tree/notes/{note_id}/ Update existing note
POST /api/tree/notes/{note_id}/delete/ Delete note and all its descendants
GET /api/tree/notes/{note_id}/details/ Get detailed information about a specific note

Integrations and tokens

GET /api/integrations/ Browsable index of the integration API.
GET /api/integrations/access-tokens/ List the records you can see.
POST /api/integrations/access-tokens/ Create a new record.
GET /api/integrations/access-tokens/{pk}/ Fetch a single record.
PUT /api/integrations/access-tokens/{pk}/ Replace a record.
PATCH /api/integrations/access-tokens/{pk}/ Update part of a record.
DELETE /api/integrations/access-tokens/{pk}/ Delete a record.
GET /api/integrations/connect-presets/
POST /api/integrations/connect-presets/generate/
GET /api/integrations/quick-connect/ One-shot endpoint: creates a token and returns a ready-to-run CLI command.
POST /api/integrations/quick-connect/ One-shot endpoint: creates a token and returns a ready-to-run CLI command.
GET /api/integrations/service-integrations/ List the records you can see.
POST /api/integrations/service-integrations/ Create a new record.
GET /api/integrations/service-integrations/{pk}/ Fetch a single record.
PUT /api/integrations/service-integrations/{pk}/ Replace a record.
PATCH /api/integrations/service-integrations/{pk}/ Update part of a record.
DELETE /api/integrations/service-integrations/{pk}/ Delete a record.
POST /api/integrations/service-integrations/{pk}/test-connection/ Test connection.
GET /api/integrations/setup-script/ Returns a bash script that installs the /nibvine skill and global MCP server.
GET /api/integrations/skill/{filename} Serves the /nibvine skill markdown file (public, no auth needed).
GET /api/integrations/write-actions/ List the records you can see.
POST /api/integrations/write-actions/preview/ Preview.
GET /api/integrations/write-actions/{pk}/ Fetch a single record.
POST /api/integrations/write-actions/{pk}/commit/ Commit.

LLM providers and keys

GET /api/llm/api/ Browsable index of the model provider API.
GET /api/llm/api/analyses/ List the records you can see.
GET /api/llm/api/analyses/{pk}/ Fetch a single record.
GET /api/llm/api/api-keys/ Get user's API key list
POST /api/llm/api/api-keys/ Create a new API key
GET /api/llm/api/api-keys/{pk}/ Fetch a single record.
PUT /api/llm/api/api-keys/{pk}/ Update API key
PATCH /api/llm/api/api-keys/{pk}/ Update part of a record.
DELETE /api/llm/api/api-keys/{pk}/ Delete API key
POST /api/llm/api/api-keys/{pk}/activate/ Activate API key
GET /api/llm/api/api-keys/{pk}/audit/ Get audit logs for an API key
POST /api/llm/api/api-keys/{pk}/deactivate/ Deactivate API key
POST /api/llm/api/api-keys/{pk}/rotate/ Rotate API key
GET /api/llm/api/prompt-templates/ List the records you can see.
GET /api/llm/api/prompt-templates/{pk}/ Fetch a single record.
GET /api/llm/api/providers/ List the records you can see.
GET /api/llm/api/providers/{pk}/ Fetch a single record.
GET /api/llm/api/token-usage/ List the records you can see.
GET /api/llm/api/token-usage/summary/ Aggregate token spend grouped by model and by operation.
GET /api/llm/api/token-usage/{pk}/ Fetch a single record.
GET /api/llm/balance/ Get current user balance and token information
POST /api/llm/balance/add-funds/ Add funds to user account (admin function)
GET /api/llm/balance/billing/ Get billing summary for period
POST /api/llm/balance/check-affordability/ Check if user can afford a request
GET /api/llm/balance/models/ Get available models with user's balance information
GET /api/llm/balance/statistics/ Get comprehensive usage statistics
GET /api/llm/balance/transactions/ Get recent transaction history
GET /api/llm/summary/estimate-context/ Estimate context size for project or branch
GET /api/llm/summary/models/ Get list of available AI models
POST /api/llm/summary/summarize/ Start asynchronous summarization task
POST /api/llm/summary/task-cancel/{task_id}/ Cancel a running task
GET /api/llm/summary/task-status/{task_id}/ Get current status of a processing task
GET /api/llm/usage/tokens/

Account

GET /api/users/me/ Profile of the authenticated user.
PUT /api/users/me/ Profile of the authenticated user.
PATCH /api/users/me/ Update the editable profile fields (email, first_name, last_name).
GET /api/users/me/balance/ Token/credit balance for the authenticated user.
GET /api/users/me/preferences/ Theme and pinned-project preferences for the authenticated user.
PUT /api/users/me/preferences/ Theme and pinned-project preferences for the authenticated user.
PATCH /api/users/me/preferences/ Theme and pinned-project preferences for the authenticated user.
GET /api/users/me/transactions/ Balance transaction history, newest first.

Authentication

POST /api/auth/token/ Exchange a username and password for an account API token.

Feedback

GET /api/feedback/ The default basic root view for DefaultRouter
GET /api/feedback/suggestion-comments/ List the records you can see.
POST /api/feedback/suggestion-comments/ Create a new record.
GET /api/feedback/suggestion-comments/{pk}/ Fetch a single record.
PUT /api/feedback/suggestion-comments/{pk}/ Replace a record.
PATCH /api/feedback/suggestion-comments/{pk}/ Update part of a record.
DELETE /api/feedback/suggestion-comments/{pk}/ Delete a record.
GET /api/feedback/suggestions/ List the records you can see.
POST /api/feedback/suggestions/ Create a new record.
GET /api/feedback/suggestions/{pk}/ Fetch a single record.
PUT /api/feedback/suggestions/{pk}/ Replace a record.
PATCH /api/feedback/suggestions/{pk}/ Update part of a record.
DELETE /api/feedback/suggestions/{pk}/ Delete a record.
GET /api/feedback/suggestions/{pk}/comments/ List or add comments on one suggestion.
POST /api/feedback/suggestions/{pk}/comments/ List or add comments on one suggestion.
POST /api/feedback/suggestions/{pk}/vote/ Cast, change or clear your vote on a suggestion.

MCP server

GET /mcp/ JSON-RPC 2.0 endpoint for MCP clients: initialize, tools/list, tools/call, ping.
POST /mcp/ JSON-RPC 2.0 endpoint for MCP clients: initialize, tools/list, tools/call, ping.

Discovery

GET /.well-known/nibvine-ai.json Discovery manifest: endpoints, protocol version, tool names and scopes.
GET /openapi/integrations.json OpenAPI description of the integration endpoints.
GET /openapi/nibvine.json OpenAPI 3.1 description of the entire Nibvine REST API.

Other

GET /api/ Browsable index of the project API.

Next

If you are connecting an AI client rather than writing HTTP by hand, the MCP server wraps the same data in tools the model can call directly.

MCP reference Quickstart