Skip to content

REST API for Notes CRUD #281

@ElioNeto

Description

@ElioNeto

REST API for Notes CRUD

Extend the existing actix-web REST API with note-specific endpoints that integrate with the Note Engine module.

New Endpoints

Notes CRUD

GET    /notes                    — List all notes (with pagination, prefix filter)
GET    /notes/{path}             — Get a single note by path
PUT    /notes/{path}             — Create or update a note
DELETE /notes/{path}             — Delete a note
POST   /notes/{path}/rename      — Rename a note (updates all indexes)

Note Relations

GET    /notes/{path}/backlinks   — List all notes linking TO this note
GET    /notes/{path}/links       — List all notes linked FROM this note
GET    /notes/{path}/graph       — Graph view data (new endpoint)

Tags

GET    /tags                     — List all tags
GET    /tags/{tag}/notes         — List notes with a specific tag (cursor pagination)

Search

GET    /search?q={query}&type=fulltext|tag|prefix
                                — Search notes by content, tag, or path prefix

Attachments

POST   /notes/{path}/attachments — Upload attachment (uses BlobStore)
GET    /notes/{path}/attachments/{name} — Download attachment
DELETE /notes/{path}/attachments/{name} — Remove attachment

Version History

GET    /notes/{path}/history     — List available versions
GET    /notes/{path}/history/{timestamp} — Get a specific version
POST   /notes/{path}/snapshot    — Create a manual snapshot

Request/Response Formats

// PUT /notes/my-note
{
  "content": "# My Note\n\nThis is a [[linked note]] with #tags",
  "frontmatter": {
    "title": "My Note",
    "aliases": ["MN"],
    "tags": ["reference"]
  }
}

// Response: GET /notes/my-note
{
  "path": "my-note",
  "content": "# My Note\n\nThis is a [[linked note]] with #tags",
  "frontmatter": { ... },
  "links": ["linked note"],
  "backlinks": ["other-note"],
  "tags": ["tags", "reference"],
  "created_at": "2026-05-25T10:00:00Z",
  "updated_at": "2026-05-25T11:30:00Z",
  "version": 3
}

Auth Integration

  • Use existing JWT/token auth middleware
  • Permission::Read for GET endpoints
  • Permission::Write for PUT/POST/DELETE
  • Permission::Admin for version history management

Acceptance Criteria

  • All endpoints return correct HTTP status codes (200, 201, 404, 409)
  • Note rename updates all link/backlink indexes
  • Pagination works correctly for note listing
  • Tag and prefix filters work
  • Attachment upload/download works via BlobStore
  • All endpoints are authenticated
  • Integration tests for each endpoint

Parent Epic

#275

Metadata

Metadata

Assignees

No one assigned

    Labels

    apifeatnotesNote storage and indexingobsidianObsidian-like note-taking features

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions