bvandeusen/FabledScribe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 50 Wiki Activity
Files
71d65442d3cc8f2ba45ba51a74d995774bc5e556
FabledScribe/docs/api-reference.md
T
bvandeusen d2f08d6113 docs(scribe): rewrite features/api-reference/README to the current product 
Resolves issue #1778 — the docs still described the pre-pivot product (in-app
LLM chat, journal, weather, web-research, push, model management) plus the
just-removed calendar/entities.

- features.md: full rewrite to the actual surfaces — notes, tasks & issues,
  projects/milestones (kanban), systems, rules & rulebooks, stored processes,
  search + knowledge-injection, graph, MCP + the Claude Code plugin, sharing,
  export/backup (v4), OIDC. Dropped chat/journal/weather/web-research/calendar/
  push/workspace/model-management; fixed the shortcuts + settings tables.
- api-reference.md: rewrite to the real endpoint surface (verified from the
  route decorators) — added Knowledge/Rulebooks/Systems/Plugin/Trash/Dashboard
  and the milestone/system sub-routes; removed Chat/Journal/Push/Quick-Capture/
  Images/assist/models.
- README.md: Quick Start no longer tells users to pull an Ollama model or size
  RAM/GPU "for LLM inference" — points at the API key + plugin instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BPtbSzA4JLMAKgFZ8VTg7Q
2026-07-19 18:23:28 -04:00

207 lines
9.6 KiB
Markdown
Raw Blame History

# 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](api-keys-and-mcp.md)). 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`) / update / delete |
| 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 |
## 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 / 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](api-keys-and-mcp.md).
Reference in New Issue View Git Blame Copy Permalink