Hjarni REST API

The account behind the token: user and plan, onboarding state, team memberships, and note limits, plus a token block describing the token itself. Folder-scoped tokens get only the user and token blocks.

{
  "user": {"id": 1, "first_name": "Evert", "email_address": "you@example.com", "plan": "pro"},
  "token": {"id": 7, "name": "smoke-test", "scope_container": null},
  "onboarding": {"completed": true, "missing_steps": [], "signals": {...}},
  "teams": [{"id": 3, "name": "Acme", "role": "owner", "notes_used": 12, "notes_limit": 25}],
  "limits": {"notes_used": 42, "notes_limit": null},
  "suggestions": {"create_team": false}
}

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",
      "summary_stale": false,
      "source_url": null,
      "archived": false,
      "favorited": false,
      "position": 1,
      "lock_version": 2,
      "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.

q

Search query string. Omitting it (or sending it blank) returns the unfiltered scope.

search_scope

"personal", "all" (default), or "team:<id>" for a specific team.

page, per_page

Pagination. Defaults to page 1, 25 per page.

exclude_body

true omits the body field from each result. Fetch full notes individually with GET /notes/:id.

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

List personal notes. Paginated.

scope

"archived", "inbox", "favorited", or omit for active notes. Trashed notes have their own endpoint: GET /notes/trash.

container_id

Filter by container.

tag

Filter by tag name.

q

Full-text search within listed notes.

page, per_page

Pagination.

exclude_body

true omits the body field from each note, so sync clients can page through metadata cheaply and fetch full notes one at a time with GET /notes/:id.

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

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

Each file's url is a signed link that expires 15 minutes after the response is generated, at the time given in url_expires_at. It needs no token of its own, so treat it as a credential and don't store it: re-request the note for a fresh link rather than saving the URL. A sync client that pages through notes first and downloads attachments afterwards should fetch the note again at download time.

{
  "id": 1,
  "title": "Weekly review",
  "body": "# Decisions\n\nSee [[42:Project plan]].",
  "summary": "Review of the week",
  "summary_stale": false,
  "source_url": "https://example.com/source",
  "archived": false,
  "favorited": true,
  "position": 1,
  "lock_version": 4,
  "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/...",
      "url_expires_at": "2026-03-15T12:45:00Z"
    }
  ],
  "linked_note_ids": [42, 58]
}

Create a note. Returns 201 on success.

title

Required. Note title.

body

Markdown content. Supports [[id:Title]] wiki-links.

summary

Short summary for quick scanning.

source_url

Canonical source URL.

container_id

Place the note in a container. Omit for inbox.

tag_list

Comma-separated tag names, e.g. "review,planning".

position

Sort position within the container. Omit to leave unpositioned; unpositioned notes sort before positioned ones.

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 are anchor-based and stay safe with or without the version: append_body, replace_find (with replace_with, which deletes the match when omitted), and insert_body (with insert_after or insert_before naming the anchor line). 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.

replace_section + section_body

Replace everything under a heading (with or without leading #), keeping the heading line. The section runs to the next same-or-higher-level heading.

append_to_section + section_body

Add content at the end of a section — the safe way to insert under a heading without knowing its last line.

rename_heading + new_heading

Rename a heading in place. The level is preserved unless new_heading carries its own # markers.

check_item / uncheck_item

Tick or untick a checklist item by its text (e.g. ship it). Matched case- and whitespace-insensitively.

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

Move a note to Trash. Returns 204. The note is recoverable — it stays restorable until it is purged, and can be brought back with POST /notes/:id/restore (see History & Trash below).

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

scope

"archived", "all" (all active, flat), or omit for active roots only.

[
  {
    "id": 5,
    "name": "Work",
    "description": "Day job projects",
    "position": 1,
    "archived": false,
    "root": 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.

name

Required. Container name.

description

Optional description.

parent_id

Nest under a parent container. Omit for root.

llm_instructions

AI instructions scoped to this container.

position

Sort position among siblings. Omit to leave unpositioned; unpositioned containers sort before positioned ones.

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

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

Move a container to the Trash, taking its sub-folders and their notes with it as one recoverable unit. Restorable for 30 days via PATCH /containers/:id/restore, then permanently removed. Returns 204, or 409 if the container was already deleted by a concurrent request.

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.