# Hjarni — how to use (mcp.ai)

Connect your Hjarni account and use 15 tools for notes straight from your AI agent. Connect with your own API key. Hjarni is a personal knowledge management platform for organizing, searching, linking, and maintaining notes, containers, and tags.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_hjarni?ms=1787293500000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `hjarni_create_container`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/hjarni`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/hjarni/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/hjarni/create/container` — Create a root or nested Hjarni container for organizing notes.
  - body: { name: string, position?: integer, parent_id?: integer, description?: string, llm_instructions?: string }
- `POST https://api.mcp.ai/api/hjarni/create/note` — Create a Markdown note in the inbox or a container. Tags named in tag_names are applied as part of creation. Free accounts are limited to 25 notes, so check account status if quota pressure is possibl
  - body: { body?: string, title: string, summary?: string, position?: integer, tag_names?: string[], source_url?: string, container_id?: integer }
- `POST https://api.mcp.ai/api/hjarni/create/notes` — Create 1-25 Markdown notes in order and return one result per input. This batch is non-atomic: successful notes remain created if another item fails.
  - body: { notes: object[] }
- `POST https://api.mcp.ai/api/hjarni/create/tag` — Create a Hjarni tag for organizing notes.
  - body: { name: string }
- `POST https://api.mcp.ai/api/hjarni/get/account/status` — Return the connected Hjarni identity, token scope, plan, teams, and current resource usage and quotas. Use this before creating many notes or attachments; Free accounts allow 25 notes, 5 attachments, 
- `POST https://api.mcp.ai/api/hjarni/get/note` — Get one Hjarni note by ID with its Markdown body, tags, container, attachments, links, and optimistic-lock version.
  - body: { note_id: integer }
- `POST https://api.mcp.ai/api/hjarni/list/containers` — List Hjarni containers as active roots, archived roots, or all active containers in a flat view. Use next_cursor to page through results.
  - body: { scope?: string, per_page?: integer, next_cursor?: string }
- `POST https://api.mcp.ai/api/hjarni/list/notes` — List and filter personal Hjarni notes, including active, inbox, archived, or favorited notes. Use next_cursor to page through results; use query for simple personal-note filtering.
  - body: { tag?: string, query?: string, scope?: string, per_page?: integer, next_cursor?: string, container_id?: integer, exclude_body?: boolean }
- `POST https://api.mcp.ai/api/hjarni/list/tags` — List all Hjarni tags and their note counts. Use next_cursor to page through results.
  - body: { per_page?: integer, next_cursor?: string }
- `POST https://api.mcp.ai/api/hjarni/list/trashed/notes` — List recoverable trashed Hjarni notes with their deletion and scheduled purge times. Use next_cursor to page through results.
  - body: { per_page?: integer, next_cursor?: string }
- `POST https://api.mcp.ai/api/hjarni/rename/tag` — Rename an existing Hjarni tag without changing its note associations.
  - body: { name: string, tag_id: integer }
- `POST https://api.mcp.ai/api/hjarni/restore/note` — Restore a note from Trash before its scheduled purge and return the active note.
  - body: { note_id: integer }
- `POST https://api.mcp.ai/api/hjarni/trash/note` — Move a note to recoverable Trash. This is not immediate permanent deletion: Hjarni retains the note for about 30 days, and RESTORE_NOTE can recover it before purge.
  - body: { note_id: integer }
- `POST https://api.mcp.ai/api/hjarni/update/container` — Update a Hjarni container's name, description, parent, position, or container-specific AI instructions.
  - body: { name?: string, position?: integer, parent_id?: integer, description?: string, container_id: integer, llm_instructions?: string }
- `POST https://api.mcp.ai/api/hjarni/update/note` — Update note metadata, placement, tags, or body. body replaces the entire Markdown body; append_body safely appends text. Provide expected_lock_version from GET_NOTE to prevent overwriting concurrent e
  - body: { body?: string, title?: string, note_id: integer, summary?: string, position?: integer, tag_names?: string[], source_url?: string, append_body?: string, container_id?: integer, expected_lock_version?: integer }

## Example prompts
- "What can I do in Hjarni?"
- "Show me a summary of my Hjarni account"

## More
- Page: https://mcp.ai/hjarni
- Agent spec (llms.txt): https://mcp.ai/hjarni/llms.txt
- Postman collection: https://mcp.ai/hjarni/postman.json