FabledScribe/docs/api-reference.md

API Reference

All endpoints are JSON over HTTP under /api, and require login unless marked (public). Browser sessions authenticate with a cookie; programmatic clients use an fmcp_ API key as Authorization: Bearer <key> (see API Keys & MCP). Claude reaches the same data through the MCP endpoint at /mcp, not these REST routes.

Health

Method	Path	Description
GET	/api/health	Health check (public)
GET	/api/version	App version (public)

Auth

Method	Path	Description
GET	/api/auth/status	{has_users, registration_open, oauth_enabled, local_auth_enabled} (public)
POST	/api/auth/register	Register (first user becomes admin)
POST	/api/auth/login	Login with username/password
POST	/api/auth/logout	Clear session
GET	/api/auth/me	Current user info
PUT	/api/auth/password	Change password
PUT	/api/auth/email	Change email
POST	/api/auth/invalidate-sessions	Evict all other sessions
POST	/api/auth/forgot-password	Send password-reset email
POST	/api/auth/reset-password	Reset password with token
GET	/api/auth/oauth/login	Begin OIDC (PKCE) flow
GET	/api/auth/oauth/callback	OIDC callback
GET	/api/auth/invitation/:token	Validate an invite (public)
POST	/api/auth/register-with-invite	Register with a token (public)

Notes

Method	Path	Description
GET	/api/notes	List notes (params: q, tag, sort, order, limit, offset, project_id, milestone_id, parent_id)
POST	/api/notes	Create note
GET	/api/notes/tags	All tags (param: q)
POST	/api/notes/:id/append-tag	Add a tag {tag}
POST	/api/notes/link-suggestions	Detect note titles as plain text → wikilink candidates
GET	/api/notes/by-title	Resolve note by exact title
POST	/api/notes/resolve-title	Get-or-create by title (wikilink click)
GET / PUT / PATCH / DELETE	/api/notes/:id	Read / replace / patch / delete
POST	/api/notes/:id/convert-to-task	Note → task
POST	/api/notes/:id/convert-to-note	Task → note
GET	/api/notes/:id/backlinks	Notes/tasks with [[Title]] references to this note
GET	/api/notes/:id/versions	Version history
GET	/api/notes/:id/versions/:vid	A specific version
POST	/api/notes/:id/versions/:vid/pin	Pin a version
GET / PUT / DELETE	/api/notes/:id/draft	Unsaved-edit draft (restore across page loads)
GET	/api/notes/graph	Knowledge-graph nodes/edges

Tasks

Method	Path	Description
GET	/api/tasks	List tasks (params: q, tag, status, priority, overdue, sort, order, limit, offset)
POST	/api/tasks	Create task (accepts a project name string → resolved to project_id)
POST	/api/tasks/planning	Start a plan (milestone + steps)
GET / PUT / PATCH / DELETE	/api/tasks/:id	Read / update / delete
PATCH	/api/tasks/:id/status	Quick status update {status}
GET	/api/tasks/:id/recurrence-preview	Preview next recurrence occurrences

Task work logs

Method	Path	Description
GET / POST	/api/tasks/:id/logs	List / append a work log {content, duration_minutes?}
PATCH / DELETE	/api/tasks/:id/logs/:log_id	Update / delete a log

Projects, Milestones, Systems, Issues

Method	Path	Description
GET / POST	/api/projects	List (owned + shared) / create
GET / PATCH / DELETE	/api/projects/:id	Read (with milestone_summary, inception) / update / delete
POST	/api/projects/:id/inception	Record what the project inherits {choices: {exclude_always_on_rulebooks, subscribe_rulebooks, design_system_id, seed_systems}} (owner-only; POST /api/projects accepts the same under inception)
GET	/api/projects/:id/inception/defaults	What binds if nobody decides — the inception card's payload
GET	/api/projects/:id/notes	Notes + tasks in this project
GET / POST	/api/projects/:id/milestones	List / create milestones
GET / PATCH / DELETE	/api/projects/:id/milestones/:mid	Read / update / delete
GET	/api/projects/:id/milestones/:mid/tasks	Tasks in a milestone
GET / POST	/api/projects/:id/systems	List / create systems
GET / PATCH / DELETE	/api/projects/:id/systems/:sid	Read / update / delete
GET	/api/projects/:id/systems/:sid/records	Records linked to a system
GET	/api/projects/:id/issues	Project issues

Knowledge browse

Method	Path	Description
GET	/api/knowledge	Unified note/task/plan/process feed (params: type, tags, sort, q, limit, offset)
GET	/api/knowledge/ids	ID-only page (two-tier pagination)
GET	/api/knowledge/batch	Fetch items by id
GET	/api/knowledge/tags	Tags in scope
GET	/api/knowledge/counts	Per-type counts

Search

Method	Path	Description
GET	/api/search	Semantic + keyword search over notes/tasks (params: q, type, limit)

Rulebooks and rules

Method	Path	Description
GET / POST	/api/rulebooks	List / create rulebooks
GET / PATCH / DELETE	/api/rulebooks/:id	Read / update / delete
GET / POST	/api/rulebooks/:id/topics	List / create topics
PATCH / DELETE	/api/rulebook-topics/:tid	Edit / delete a topic
GET	/api/rules	List rules
POST	/api/rulebook-topics/:tid/rules	Add a rule to a topic
GET / PATCH / DELETE	/api/rules/:id	Read / update / delete a rule
POST	/api/projects/:id/rulebook-subscriptions	Subscribe a project to a rulebook
GET	/api/projects/:id/rules	Applicable rules for a project
POST	/api/projects/:id/rules	Create a project-scoped rule
POST / DELETE	/api/projects/:id/suppressions/rules/:rid	Suppress / unsuppress a rule
POST / DELETE	/api/projects/:id/suppressions/topics/:tid	Suppress / unsuppress a topic
POST / DELETE	/api/projects/:id/exclusions/rulebooks/:rid	Exclude / include an always-on rulebook for this project (inception)

Sharing

Method	Path	Description
GET / POST	/api/projects/:id/shares	List / add project shares {user_id?, group_id?, permission}
PATCH / DELETE	/api/projects/:id/shares/:sid	Update permission / remove
GET / POST	/api/notes/:id/shares	List / add note shares
PATCH / DELETE	/api/notes/:id/shares/:sid	Update permission / remove
GET	/api/shared-with-me	All resources shared with the current user

Groups

Method	Path	Description
GET / POST	/api/groups	List / create groups
GET / PATCH / DELETE	/api/groups/:id	Read / update / delete
GET / POST	/api/groups/:id/members	List / add members {user_id, role}
PATCH / DELETE	/api/groups/:id/members/:uid	Update role / remove

Notifications

Method	Path	Description
GET	/api/notifications	List in-app notifications
GET	/api/notifications/count	Unread count
POST	/api/notifications/:id/read	Mark one read
POST	/api/notifications/read-all	Mark all read

Profile and Settings

Method	Path	Description
GET / PUT	/api/profile	Read / update the per-user profile
GET / PUT	/api/settings	Read / update key-value settings
GET	/api/settings/search	SearXNG configuration status

API keys

Method	Path	Description
GET / POST	/api/api-keys	List / create fmcp_ keys (key shown once)
DELETE	/api/api-keys/:id	Revoke a key

Plugin (Claude Code)

Method	Path	Description
GET	/api/plugin/context	SessionStart context payload (rules + active-project)
GET	/api/plugin/retrieve	Title-first knowledge-injection candidates
GET	/api/plugin/processes	Stored Processes for skill-stub sync
GET	/api/plugin/prior-art	Write-path hint for the plugin hooks (params: path, code, repo, shapes, exclude_ids, exclude_sync_ids, exclude_derive); returns context, note_ids, sync_note_ids, stamped, divergence, derive, derive_keys
GET / POST	/api/projects/<id>/coverage, …/coverage/refresh	Shape-ledger accounting (pattern_coverage line, counts, derive_groups, derive_new, divergence, recheck)
GET / PUT	/api/plugin/marketplace-url	Read / set the plugin marketplace URL

Dashboard, Export, Trash, Users

Method	Path	Description
GET	/api/dashboard	Home dashboard payload
GET	/api/export	Personal export (format=markdown ZIP or format=json)
GET	/api/trash	List trashed items, grouped by delete batch
POST	/api/trash/:batch/restore	Restore a batch
DELETE	/api/trash/:batch	Purge a batch (irreversible)
GET	/api/users/search	Search users by prefix (for sharing)

Admin

Method	Path	Description
GET	/api/admin/backup	Export backup (format v4; ?scope=user for own data)
POST	/api/admin/restore	Restore from a backup
GET / DELETE	/api/admin/users · /api/admin/users/:id	List / delete users
GET / PUT	/api/admin/registration	Get / toggle registration
GET / PUT	/api/admin/smtp · POST /api/admin/smtp/test	SMTP config + test email
GET	/api/admin/logs · /api/admin/logs/stats	Log entries + category counts
GET / PUT	/api/admin/base-url	Get / set the public base URL
GET / PUT	/api/admin/db-maintenance (+ /health, POST /run)	VACUUM schedule, health, manual run
POST / GET / DELETE	/api/admin/invitations (+ /:id)	Create / list / revoke invite links

Scribe MCP

Claude clients connect to the built-in MCP server at POST /mcp (streamable HTTP, Bearer auth with an fmcp_ key), served by src/scribe/mcp/. It is not a REST surface — it exposes the same data as typed tools (create_note, create_task, start_planning, search, enter_project, list_always_on_rules, …) with server-level usage guidance delivered in the MCP instructions block. See API Keys & MCP.