Hjarni REST API

Overview of your personal knowledge base with counts and recent notes.

{
  "inbox_count": 3,
  "notes_count": 42,
  "archived_count": 7,
  "containers_count": 8,
  "tags_count": 12,
  "recent_notes": [
    {
      "id": 1,
      "title": "Weekly review",
      "body": "# Decisions\n\n...",
      "summary": "Review of the week",
      "source_url": null,
      "archived": false,
      "favorited": false,
      "position": 1,
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z",
      "tag_list": "review,planning",
      "tags": [{"id": 1, "name": "review"}, {"id": 2, "name": "planning"}],
      "container": {"id": 5, "name": "Work"},
      "files": []
    }
  ]
}

Full-text search across notes. Returns paginated note objects.

GET /api/v1/search?q=weekly+planning&search_scope=personal

List personal notes. Paginated.

Notes without a container. Paginated. Same response shape as listing notes.

Full note with body, tags, container, files, and linked note IDs.

{
  "id": 1,
  "title": "Weekly review",
  "body": "# Decisions\n\nSee [[42:Project plan]].",
  "summary": "Review of the week",
  "source_url": "https://example.com/source",
  "archived": false,
  "favorited": true,
  "position": 1,
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T12:30:00Z",
  "tag_list": "review,planning",
  "tags": [
    {"id": 1, "name": "review"},
    {"id": 2, "name": "planning"}
  ],
  "container": {"id": 5, "name": "Work"},
  "files": [
    {
      "id": 10,
      "description": "Slide deck",
      "filename": "slides.pdf",
      "content_type": "application/pdf",
      "byte_size": 204800,
      "url": "https://hjarni.com/rails/active_storage/blobs/..."
    }
  ],
  "linked_note_ids": [42, 58]
}

Create a note. Returns 201 on success.

POST /api/v1/notes
{
  "note": {
    "title": "Weekly review",
    "body": "# Weekly review\n\nKey decisions...",
    "summary": "Review of the week",
    "source_url": "https://example.com/source",
    "container_id": 12,
    "tag_list": "review,planning"
  }
}

Update any note field. Only include the fields you want to change.

PATCH /api/v1/notes/1
{
  "note": {
    "body": "Updated content",
    "tag_list": "review,done"
  }
}

Optional expected_lock_version guards against concurrent edits. Every note read returns a lock_version integer. Echo it back on your write and the server rejects with 409 Conflict if someone else saved in the meantime.

PATCH /api/v1/notes/1
{
  "note": {
    "body": "Updated content",
    "expected_lock_version": 5
  }
}

# 409 Conflict response when the version no longer matches:
{
  "error": "Note was modified since you last read it. Re-read and re-apply...",
  "current_lock_version": 7,
  "last_edited_by": "alice@example.com",
  "last_edited_by_agent": null,
  "last_edited_at": "2026-05-27T14:32:00Z"
}

Surgical body edits (replace_find, insert_after, append_body) are anchor-based and stay safe with or without the version. Pass expected_lock_version whenever you also touch non-body fields and want a stale-write guard.

For long notes, prefer the structured patch operations over a full-body replacement — they target a heading or checklist item instead of the whole document, so a stale read can't clobber unrelated sections. Each targets exactly one match and is mutually exclusive with the other body modes.

PATCH /api/v1/notes/1
{
  "note": {
    "append_to_section": "## Open Questions",
    "section_body": "- Should we ship Friday?"
  }
}

Permanently delete a note. Returns 204.

List containers. Paginated. Returns root-level containers by default.

[
  {
    "id": 5,
    "name": "Work",
    "description": "Day job projects",
    "position": 1,
    "archived": false,
    "llm_instructions": "Use formal tone.",
    "created_at": "2026-03-01T09:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z",
    "notes_count": 12,
    "children_count": 3,
    "parent": null
  }
]

Single container with counts and parent info.

Create a container. Returns 201.

POST /api/v1/containers
{
  "container": {
    "name": "Research",
    "description": "Papers and reading notes",
    "parent_id": 5
  }
}

Update name, description, parent, position, or instructions.

Delete a container. Notes inside it are moved to the inbox. Child containers become root-level. Returns 204.

List all tags with note counts. Paginated.

[
  {
    "id": 1,
    "name": "review",
    "created_at": "2026-03-01T09:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z",
    "notes_count": 8
  }
]

Single tag with note count.

Create a tag. Returns 201.

POST /api/v1/tags
{
  "tag": {"name": "research"}
}

Rename a tag. Send {"tag": {"name": "new-name"}}.

Delete a tag. Returns 204. Notes keep their content; only the tag association is removed.