Rootr — Team Knowledge Base

Rootr User Guide

A guide for people using Rootr for the first time. We unpack every term as we go, so you can follow along even if the jargon is new to you. First things first — we start by connecting your AI to Rootr.

Last updated: 2026-07-14

Connect & start

①Integration — Connect your AI to Rootr

By the end of this chapter, the AI you use (for example, Claude) will be able to read, edit, search, and ask questions of your documents in Rootr directly.

First, a few terms

Rootr is a "document tool that your AI writes alongside you." So the very first thing to do is connect your AI to Rootr. Once you know the terms below, this whole chapter becomes easy.

• AI agent: an AI that does not just chat with you but actually carries out the work you ask of it. Examples are programs like Claude Code, Claude Desktop, and Codex. Throughout this guide, whenever you see "agent," just think "your AI."
• API: a channel through which programs exchange information. Instead of a person clicking buttons on a screen, your AI uses this channel to send Rootr requests like "show me this document" or "add a line here."
• API key: the "key" that opens that channel, and also your ID badge. It is a long string that starts with `rootr_`, and only an AI holding this key can reach your material. That is why, like a password, you must never show it to anyone.
• MCP: a rule (a convention) that lets an AI use outside tools in a standard way. In plain terms, it is a "universal adapter between your AI and Rootr." Connect over MCP and your AI treats Rootr like a folder on its own computer.
• Workspace: the space where your documents and folders live. Think of it as one "work room" for a company. Each workspace has its own id.

There are broadly four ways to connect: (1) the remote connector — paste a single URL and log in; (2) one-click MCP, which builds a key in a few clicks; (3) editing config files yourself; and (4) the API, which you call directly from a program. Even if you know nothing about programming, (1) alone is enough. Here it is as a picture.

Once your AI connects to Rootr over MCP or the API, holding your key (API key), it can work with documents, questions, and data directly.

Sections 1.1–1.5 are alternatives, not a checklist — pick just ONE. If you are not a developer, 1.1 is all you need. (1.6 onward is reference material.)

1.1 Remote connector — paste a URL, log in, done (easiest, recommended)

No install, no terminal, no config files. Claude and ChatGPT both connect with this one address:

Copy all

https://rootr.io/mcp

1. In your AI's settings, open Connectors → Add custom connector, and paste the address above.
2. A Rootr screen opens in your browser. Log in, pick the workspace to connect and a permission level (read-only / read + write), then press Allow.
3. Rootr tools appear in your AI. Try asking: "What documents are in my workspace?"

• ChatGPT supports connectors on paid plans only.
• For ChatGPT to also create and edit documents, turn on Developer mode in the connector's advanced settings (OpenAI policy).

Connecting automatically creates an "MCP remote connector" key in Settings → Integrations. Disconnect = revoke that key (access stops immediately).

A screenshot-by-screenshot guide to connecting Claude and ChatGPT →

1.2 One-click MCP key setup — the locally-installed way

Rootr builds the settings you need for the connection automatically. All you do is copy them and paste them into your AI. Here is the order:

1. Open Settings from the left-hand menu.
2. Inside Settings, click the Integrations tab.
3. Find the "AI agent integration (MCP)" item and press the Create MCP key… button.
4. Give the key a name (for example, "Claude on my laptop"), choose how much access to allow (permissions), and press Create. A configuration with your key (API key) already filled in then appears automatically in the code box below.
5. Press the copy button that matches the AI you use, and paste it in as guided below.

The one-click MCP integration screen in Settings → Integrations. It shows a copy-ready configuration with the issued key filled in, plus per-target copy buttons.

There are three copy buttons, depending on the kind of AI you use.

• Claude Code (Claude in the terminal): paste the one-line command you copied straight into a terminal window and run it, and the connection is done.
• Claude Desktop (the app): put what you copied into the Claude settings file (`claude_desktop_config.json`) and restart the app. You can find where this file lives in the Claude Desktop settings screen.
• Codex CLI: paste the copied command into the terminal and it is saved to your config file automatically.

Important: the API key (your key) is shown on screen only once, at creation time. Once you close the window you cannot see it again, so copy it somewhere safe. If you ever lose it or it leaks, just delete (revoke) that key from the key list in Settings → Integrations and create a new one.

1.3 Registering MCP manually (for those who edit config files themselves)

If you are comfortable with development and want to manage config files directly, add it as shown below. This is a setting that tells your AI to "run a small program (rootr-cli) that connects to Rootr." Put the key you made above into `ROOTR_API_KEY`, and your workspace id into `ROOTR_WORKSPACE`.

Copy all

{

"mcpServers": {

"rootr": {

"command": "npx",

"args": ["-y", "rootr-cli", "mcp"],

"env": {

"ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",

"ROOTR_WORKSPACE": "ws_123"

}

}

}

}

For Claude Code, put this into the `~/.claude.json` file; for Claude Desktop, put it into the `mcpServers` part of the `claude_desktop_config.json` file. If you installed `rootr-cli` globally on your computer, you can shorten `command` to `"rootr"` and `args` to `["mcp"]`.

1.4 The rootr CLI — a person, straight from the terminal

A CLI (command-line tool) is a way to work with Rootr by typing commands into a black terminal window. It is handy when a person works directly without an AI, or when you put it into a script that runs automatically at a set time. Try running the commands below in order.

Copy all

# 1) Install — add the rootr command to your computer

npm install -g rootr-cli

# 2) Configure — register your key and workspace once, and it keeps being used

rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123

# 3) Usage examples

rootr ls /notes # list the documents inside the /notes folder

rootr read /notes/todo.md # open one document and read its content

rootr append /notes/log.md "Deploy finished" # safely add one line to the end of a document

rootr edit /notes/todo.md --find "- [ ] Deploy" --replace "- [x] Deploy" # change a specific line

rootr search "deploy procedure" # search across the whole workspace

rootr ask "why did latency rise after last week's deploy?" # ask the AI for the root cause

• How to write paths: if it starts with a slash (/), it is read as a "folder path"; otherwise it is read as a document's unique number (id). Rootr figures this out for you.
• We recommend "append": it only adds to the end of a document rather than rewriting the whole thing, so it never conflicts even when other people or other programs edit at the same time.
• If you need a line-by-line explanation, type `rootr --help` and the usage appears.

1.5 Calling the REST API directly (for programmers)

If you are building your own program, you can call Rootr with an internet request (HTTP) from any language. The address is `https://rootr.io/api/v1\`, and with each request you carry your key in a label called `x-api-key`. Below are examples you can try right away in the terminal.

Copy all

# Safely add one line to the end of a document

curl -X POST https://rootr.io/api/v1/docs/by-path/append \

-H "x-api-key: rootr_xxxxxxxxxxxxxxxx" \

-H "content-type: application/json" \

-d '{"workspaceId":"ws_123","path":"/notes/log.md","content":"Deploy finished"}'

# Ask your knowledge a question and get an answer with evidence

curl -X POST https://rootr.io/api/v1/workspaces/ws\_123/ask \

-d '{"question":"why have payment failures increased?"}'

It is fine if you do not know exactly what each command means. The point is that you "carry your key in the header and send a request to the address." You can find the complete list of every request you can make in the technical document (OpenAPI) linked from ⑩ Reference.

1.6 The two kinds of keys (API keys) and their permissions

There are two kinds of keys, and they differ in how wide a range they can open. Each key also carries a set of permissions (scopes) that decide "how much it is allowed to do." Allowing only as much as you need is the safe choice.

Type	Range it can open	When to use it
Workspace key	Only within that one workspace (work room)	Reading/writing documents, searching, asking, and nearly every other connection — usually this is enough
Account key (PAT)	Your whole account (all of your workspaces)	Only when the AI needs to create an entire new workspace

• Examples of permissions (scopes): docs:read (read documents) · docs:write (edit documents) · graph:read (browse knowledge) · ask (ask questions) · webhooks:manage (set up notifications). If you only want it to read, turn on docs:read alone.
• The principle: for most connections, a workspace key is enough. An account key has broad permissions, so use it only when you truly need it.

Keys are shown only once. Managing and revoking (deleting) them is all done in one place — the key list in Settings → Integrations.

1.7 Tips for putting your AI to work

Once connected, you just tell your AI in plain language ("summarize this document and add it below"). For results that are safer and more accurate, have it follow the points below.

• For adding content, have it use "append" first, and for partial changes, "find and replace" (edit). The approach of rewriting the whole document can accidentally erase existing content, so use it only when it is truly needed.
• When building a workspace from a structure up, have the AI plan first, ask a few questions, and only then create it (so it does not build blindly).
• If you have set the AI to receive change notifications (webhooks) again, have it ignore "changes the AI itself made." Otherwise you get an endless loop where it reacts to the very notifications it created.

1.8 The list of tools your AI can use (38 in total)

Once connected, your AI can use the tools below. This is a table summarized by category; a detailed description of each tool is in ⑩ Reference. For now, just get a sense of "wow, I can have it do this many different things."

Group	Count	Representative tools (what they do)
Documents	6	list · read · append · find and replace · full rewrite · search
Creating workspaces	4	see my workspaces · plan a structure · create a new workspace · apply to an existing one
Data records (LOG)	5	create a logbook · add an entry · query · statistics · edit an entry's format
Questions (RCA)	1	ask in natural language and get a cited answer
Issue (task/bug) management	6	create an issue · list · detail · edit · comment · create a tracker
Table (DATABASE) rows	5	read a table · list rows · add a row · edit a row · delete a row
Presentations	6	create a deck · read · add a slide · edit a slide · reorder · settings
Change notifications (webhooks)	3	list notifications · create a notification · delete a notification
Versions / deletion	2	view a document's version history · send a document to the trash

②Get started in 5 minutes

From sign-up to your first document, and building a whole workspace with AI — it takes just five minutes.

If Rootr is new to you, just follow this order. No development knowledge is needed.

2.1 Sign up and log in

• You can sign up with an email and password, or start in one click with a Google account.
• The first time you log in, you see a prompt: "Create your first workspace." A workspace is your own space that holds documents and folders.

2.2 Creating documents and folders

On the left of the screen is a tree (a list that unfolds like branches). Here you create folders to organize things and create documents inside them. Think of it just like the folders and files on your computer.

A newly created workspace and the document tree (list of folders and documents) on the left.

2.3 Building it all at once with "Create with AI"

You do not have to build everything piece by piece from a blank screen. Write in one sentence "what you want to do" (for example, "make me a space to prepare a new product launch"), and after asking you a few questions, the AI automatically builds a ready-to-use structure complete with folders, documents, and tables.

The "Create with AI" window. Write what you want to do as a sentence and it generates a workspace structure automatically.

When you save a document, its contents are automatically organized into a "knowledge graph" in the background (details in chapter ⑥). Then go straight to chapter ① and connect your AI — that is where the real power of Rootr begins.

Documents & structure

③Writing documents together (basics)

Many people can write comfortably at the same time, and just by saving, the content automatically becomes searchable, queryable knowledge.

Rootr documents are made of pieces called "blocks." A heading, a paragraph, a list, a table, an image — each is a block. You can drop them in wherever you like and reorder them, which makes writing far more flexible.

• Real-time co-editing: even when several people open the same document and edit it at once, everyone's changes show up instantly. You can also see who is looking at what.
• Version history (an automatic save log): every time you edit a document, its previous state is saved automatically. Even if you delete something by mistake, you can roll back to an earlier version (the clock icon in the top right).
• Special blocks: you can add highlight boxes (callouts), tags (labels), and mermaid diagrams — pictures like flowcharts drawn with code. Even when the AI writes a document, it draws these diagrams automatically.
• Content added from outside shows in real time too: when an AI or a program adds text to a document via the API, it appears right away on the screen of whoever has that document open.

The block editor screen. Alongside a heading and a list, a flowchart (mermaid diagram) is drawn.

Below is the version history screen. The moments you edited the document remain as a list, so you can check or roll back to the content at any of those points anytime.

The document's version history panel. The moments of editing are listed in chronological order.

④Document kinds (node types) in full

Do not force everything into a plain document. Picking the kind that fits your purpose makes things much easier.

"Node" is the word for each item that goes into the tree (the list on the left). A document is a node, a folder is a node, a table is a node. Rootr has several kinds of nodes, as below, and you pick the one that fits what you are trying to do. First, here is the whole picture at a glance; then we explain the important ones one by one.

Kind	Use it when	Key features
DOCUMENT	Writing — descriptions, plans, meeting notes, etc.	Block editor · co-editing · versions · automatic knowledge-building
FOLDER	Grouping several items to organize them	Grouping + passing permissions down to children
DATABASE (table)	Managing things as a list — to-dos, requirements, issues	A table with a defined format per column + 4 views
SPREADSHEET	Tables that need calculation — budgets, quotes	A table with formulas (=sum, etc.)
WHITEBOARD	Sketching ideas freely with drawings and shapes	Free placement on an infinite canvas
FORM (survey/form)	Getting responses from people outside	A form to fill in → collected into a table automatically
ISSUE_TRACKER (issues)	Tracking bugs and tasks by number	GitHub-style issues (#number · status · label · comments)
PRESENTATION	Slide presentation materials	A slide deck (16:9)
LOG (data records)	Recording metrics, incidents, events	A formatted logbook → data lineage (⑦)

DATABASE (table) — a list with a defined format

Think of it as a spreadsheet table crossed with a structured database. For each cell (column) you set a format — "this column is text, that one is a date, this one is a status (a choice)." You can look at the same data in four ways — as a table, as a kanban board (where cards form columns by status), as a calendar, and as a timeline. You can add and edit rows both on the screen and by asking the AI to do it.

A DATABASE node viewed as a kanban board. Cards sit in the To do / In progress / Done columns.

WHITEBOARD · PRESENTATION · FORM

• Whiteboard: a wide canvas where you draw freely with shapes and connectors. Great for structure diagrams or organizing ideas.
• Presentation (PRESENTATION): where you make slides. The "text" you write in a slide's title, body, and notes is linked automatically into the knowledge graph, so always write important content as text, and add descriptions (captions) to images.
• Survey/form (FORM): a form you send as a link to people outside the workspace to collect responses. The responses you receive are gathered automatically into a table (DATABASE).

A WHITEBOARD freeform canvas screen.

A PRESENTATION slide-deck editing screen.

ISSUE_TRACKER (issues) · LOG (data records)

• Issue tracker: turn each bug or task into an "issue" and track it with a number (#1, #2…), a status (open/closed), labels, an assignee, and comments. It works the same way as the issues in a development-collaboration tool (GitHub).
• LOG (data logbook): a place to put records that pile up over time (for example, server response times or incident events) in a defined format. When you use a "relation" column here, a "data lineage" is created automatically, tracing where each record came from (chapter ⑦).

The issue-list screen of an ISSUE_TRACKER.

A LOG (data logbook) screen. A record table filled with level, message, and data values.

⑤Permissions · sharing · public publishing

Decide easily, at the folder level, who can see what — and if you need to, publish a specific document to the internet.

When you use it as a team, the most important thing is "who can see how much." Rootr handles this very simply.

Roles (permission tiers)

• Owner: manages everything in the workspace. Admin: manages members and settings. Member: creates and edits documents. Viewer: can only view.
• Permissions are inherited automatically from a folder to the documents inside it. In other words, set permissions once on a folder and they apply to everything within it. You can also make a specific document an exception and set it separately.

Private · shared · public

• Private nodes: turn on the "Invited people only" switch and you can hide a document/folder you created so that only you (and the people you invited) can see it.
• Invite by share link: send a link to invite people from outside the workspace.
• Public publishing: you can make a specific document viewable by anyone at an internet address (`/p/document-name`). Outsiders can propose edits to a public document ("how about changing it this way?"), and the owner can accept (merge) or reject those proposals — just like collaboration on documents (Git).

The share window, the "Invited people only" private switch, and the public publishing screen.

AI & data

⑥The knowledge graph and asking AI (RCA)

Just by saving documents, scattered information becomes a connected "knowledge graph," and when you ask "why?" on top of it, you get an answer backed by evidence.

What is a knowledge graph?

When you save a document, Rootr automatically extracts the "important things" and "relationships" inside it in the background. For example, it finds people, teams, services, systems, incidents, and decisions, and creates connections like "this incident happened in that service." A map connected this way, with dots (things) and lines (relationships), is called a "knowledge graph," or in plain terms a "knowledge map." Several scattered documents become one connected picture.

Things mentioned across different documents get connected into one knowledge map — so you can trace around "payment failure" to find the cause.

• Mini-map: open a single document and you can immediately see, as a small map, the things that document mentions.
• Exploring the whole map: on the graph screen you can search for a specific thing, see what is connected around it, and follow what paths exist between two things.

The knowledge-graph exploration screen. Things are connected as dots and relationships as lines.

Ask — asking "why?" (root-cause analysis)

When you ask the Ask feature a question in everyday language (for example, "why has payment kept failing since last week?"), Rootr searches both the knowledge graph and your documents and gives you an answer with the evidence attached (which sentence of which document it came from). It is especially strong at root-cause analysis (RCA) — tracing "what the cause is." You can ask the same question through the CLI or API `ask` you learned about earlier.

The Ask panel showing an answer to a natural-language question with evidence (sources) attached.

⑦Data records and lineage (LOG)

Pile up records of numbers and events, and "where this result came from" is connected automatically, like a picture.

What is a LOG (data logbook)?

A LOG is a special table that holds records piling up over time. What sets it apart from an ordinary table is that you set "the format of each column" before you put anything in — this column is text, this one is a number, this one is a severity (info/warning/error), this one is a timestamp, and so on. It then filters out odd values that come in and automatically flags values that differ greatly from the norm (outliers). It is great for recording things like server response times, incident events, or job-processing counts.

What is "lineage"?

Lineage (data lineage) is the connection of "where this data came from, and what came from it here." Picture a family tree and it becomes easy. When you use a "relation"-format column in a LOG, one record points to another, and the moment it does, a lineage line is drawn automatically between the two. That way you can later trace, as a picture, "what earlier event was the cause of this incident?"

Link records with a "relation" column and the lineage runs automatically from the causing event to the final result.

• How to put data in: it supports on-screen entry, file upload (CSV/Excel), and even real-time sending from a program or sensor.
• Automatic connection: put a value in a relation column and a lineage line appears on its own. There is nothing to manage separately.
• Statistics: you can see summaries like count, average, and maximum, by time and by item.

A data-lineage graph created by a LOG's relation columns. Arrows run from one record to another.

Automation & admin

⑧Automation (change notifications · CLI · issues)

You can make the next task roll forward automatically whenever something changes.

What is a webhook (change notification)?

A webhook is a feature that "automatically tells another program you have designated whenever something happens in Rootr." For example, "when a document in this folder changes, send a notification to our team chat." It lets things react to change without a person constantly watching.

• Narrowing the scope: instead of the whole workspace, you can limit it to a specific folder or document, or filter by tag (label) so you are only notified about what you want (a parent folder's tags apply inside it too).
• What changed: it is categorized as document / comment / system, and it sends only "the part that changed (the diff)" rather than the entire content, which is safer.
• Signing key: a key that verifies the notification really came from Rootr is issued once, at creation time. Store it on your receiving server.

The issue tracker also updates the screen in real time (SSE) and can connect to outside systems in both directions. If you set the CLI/AI connections you learned earlier to run automatically at set times, you can build automatic flows too, like "when a document changes → the AI appends a summary."

The webhook (change notification) creation screen. You choose the scope, tag filter, and the events to send.

⑨Account · workspaces · plans

Move between several accounts, raise your plan to match your team's size, and bring in your existing material.

• Using several accounts at once: like a company account and a personal account, you can be logged in to several accounts together and switch between them with a click.
• Plans: a mix of number of people (seats) · storage space · AI usage. AI features can be used up to a set amount of "graph credits" per plan. Check the exact prices and what is included on the Plans page. You can start free for up to 3 people.
• Import: you can bring documents that were elsewhere into a workspace.

The settings screen for account switching, plans, and import.

⑩Reference (detailed material for developers)

The exact specification you need for connecting by program, and the error guide to look at when you get stuck.

This is a collection of reference material for people building their own programs. If you only use Rootr through the screen, you can skip this chapter.

• Full REST API specification: a document listing every request you can make in a machine-readable format — `/api/api-docs-json`.
• GraphQL schema: the full structure of another way to query — `/api/graphql/sdl`.
• Details of the 38 AI tools: the manual (README) for `rootr-cli` describes in detail what each tool does.

Common errors and how to fix them

Number	Meaning	Do this
401 / 403	The key is missing, or permissions are insufficient	Check that the API key is correct and that the key has the permission (scope) it needs turned on
409	The sentence to "find and replace" is missing, or there are several so it is ambiguous	Specify the sentence to change more precisely (uniquely), or re-read the document and try again
412	The document changed while you were reading it	Re-read the document to bring it up to date, then try again

When a connection does not work, it is usually solved in chapter ①'s "Keys and permissions." Check that first.