> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revilico.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# RevNotes

> Read, write and share RevNotes notes and folders through the Revilico REST API or MCP server, in markdown or HTML, without overwriting web app edits.

The API reads and writes the notes and folders of [RevNotes](https://docs.revilico.bio/docs/revnotes.md), the same ones you see in the web app. An AI app can write up a run's results as a note, add to your lab notes, or read a note you point it to.

* Notes have a title and a body. Their ids start with `note_`.
* Folders hold notes and don't nest. Their ids start with `notefld_`.
* A note or folder can be linked to a project. Project members can then see it.

## Who can see a note

A note's owner is the person who wrote it. Folders belong to whoever created them. Anyone else needs to be in the owner's organization, and then has the strongest access of:

* a share of the note (read or write)
* a share of the note's folder (read or write), which covers every note in it
* owning the note's folder (write)
* their role in the note's project, or in its folder's project: owners and editors can write, viewers can read

Notes and folders you can't see answer `404 NOT_FOUND`, so the API doesn't reveal that they exist.

Each note and folder has `access`, which says what you can do:

| `access` | Can |
| - | - |
| `owner` | Everything, including delete and share |
| `write` | Edit the note, or for a folder rename it and add and edit its notes |
| `read` | Read |

## List and read notes

`GET /v1/notes` lists the notes you can read, most recently changed first. It returns titles and metadata, not content. Filter with `folderId`, `projectId`, or `q`, which matches titles.

```bash theme={null}
curl "https://public-api.revilico.bio/v1/notes?q=screening" \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

`GET /v1/notes/{noteId}` returns a note with its content, as markdown by default:

```bash theme={null}
curl https://public-api.revilico.bio/v1/notes/note_4e2a… \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

```json theme={null}
{
  "id": "note_4e2a…",
  "title": "Round 3 screening",
  "folder": { "id": "notefld_91b0…", "name": "KRAS project" },
  "project": { "id": "proj_7c1f…", "name": "KRAS G12D" },
  "owner": { "name": "Alex Kim", "email": "alex@example.com" },
  "access": "owner",
  "createdAt": "2026-10-20T09:01:12.000Z",
  "updatedAt": "2026-10-27T10:40:03.000Z",
  "format": "markdown",
  "content": "## Top hits\n\n| Ligand | Score |\n| --- | --- |\n| L-104 | -9.8 |"
}
```

`GET /v1/note-folders` lists the folders you can read, with how many notes each holds.

## Markdown and HTML

The web app stores notes as HTML from its editor. The API speaks markdown by default and HTML when you ask:

* **Reading:** `format=html` returns the note as stored, formatting included.
* **Writing:** send `"format": "html"` with HTML content. Markdown is converted to the HTML the editor uses. HTML is cleaned to the same elements, so the note opens in the editor as you wrote it.

Markdown can't carry everything the editor can. Reading a note as markdown drops:

* colours, font sizes and text alignment
* image sizes
* merged table cells (the extra columns stay empty)

Tables become markdown tables, with the first row as the header. Images stay as links. Underlined text comes back as inline HTML, and math as `$…$`. Notes written before the rich editor are plain text in either format.

These losses matter only when you replace a note's body. Adding to a note never changes what is already in it.

## Create a note

```bash theme={null}
curl https://public-api.revilico.bio/v1/notes \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "RevRedox: phenothiazine",
    "content": "Oxidation potential **0.59 V** vs SCE.\n\nRun: run_3f2b…",
    "folderId": "notefld_91b0…"
  }'
```

You own the notes you create. `folderId` needs write access to that folder; a note in a project's folder joins that project. `projectId` links the note to a project where you are an editor or owner.

Create a folder with `POST /v1/note-folders` and a `name`. Names must be unique among your folders; a duplicate answers `409 CONFLICT`. Rename a folder with `PATCH /v1/note-folders/{noteFolderId}`.

## Change a note

`PATCH /v1/notes/{noteId}` renames a note, adds to its end, or replaces its body. It needs write access.

### Add to the end

Prefer `append`. It adds to the end of the note and leaves the rest, formatting included, as it is.

```bash theme={null}
curl -X PATCH https://public-api.revilico.bio/v1/notes/note_4e2a… \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "append": "## 27 October\n\nRevScreen finished: 12 hits below -9 kcal/mol." }'
```

### Replace the body

`content` replaces the whole body. It needs `expectedUpdatedAt`: the note's `updatedAt` when you read it.

```bash theme={null}
curl -X PATCH https://public-api.revilico.bio/v1/notes/note_4e2a… \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "## Top hits\n\n…",
    "expectedUpdatedAt": "2026-10-27T10:40:03.000Z"
  }'
```

If the note has been saved since, nothing changes and the API answers `409 CONFLICT`. The web app saves as people type, so read the note again and retry.

> [!WARNING]
>
> Replacing a formatted note with markdown drops its colours, font sizes and alignment. To edit a formatted note in place, read it with `format=html`, change the HTML and send it back with `"format": "html"`.

You can't send `content` and `append` together.

## Share notes and folders

Only a note's or folder's owner can share it, with active members of their organization. Give each person as an email or a `user_…` id from [`GET /v1/org/members`](https://docs.revilico.bio/developers/sharing#find-people-to-share-with).

```bash theme={null}
curl https://public-api.revilico.bio/v1/notes/note_4e2a…/shares \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": ["priya@example.com"], "permission": "write" }'
```

* `permission` is `read` (the default) or `write`.
* Sharing again with someone who has the note sets their permission to the new one.
* Sharing a folder with `POST /v1/note-folders/{noteFolderId}/shares` gives access to every note in it, including notes added later.
* Nobody is notified. Tell people yourself.

`GET …/shares` lists a note's or folder's shares. The owner sees every share; anyone else sees only their own. People who reach a note through its folder or a project aren't listed.

`DELETE …/shares/{noteShareId}` removes a share. The owner can remove any share; the person it was shared with can remove their own. They may keep access through the note's folder or a project.

## Delete a note

`DELETE /v1/notes/{noteId}` deletes a note and its shares for good. There is no trash. Only the note's owner can delete it, and images it links to are not deleted. Deleting is available in the REST API only, not through MCP.

## Limits

| | Limit |
| - | - |
| Note content, or text to append | 90,000 characters per request |
| Note title | 200 characters |
| Folder name | 100 characters |
| People per share request | 20 |
| Page size (`limit`) | 50 by default, up to 100 |

## Not in this version

* Uploading images. Link images by URL instead.
* Moving a note to another folder.
* Deleting folders.
* Searching note content. `q` matches titles only.
* Exporting notes.
* Deleting notes, or sharing folders, through MCP. Use the REST API.

## Scopes

| Action | Scope |
| - | - |
| List and read notes, folders and their shares | `data:read` |
| Create and change notes and folders, delete notes | `files:write` |
| Share and stop sharing notes and folders | `runs:write` |

## MCP tools

| Tool | Does |
| - | - |
| `list_notes` | Lists notes, filtered by folder, project or title |
| `get_note` | Reads a note, as markdown or HTML |
| `create_note` | Creates a note, optionally in a folder or project |
| `append_to_note` | Adds to the end of a note, leaving the rest as it is |
| `update_note` | Renames a note or replaces its body, with `expectedUpdatedAt` |
| `list_note_folders` | Lists note folders |
| `create_note_folder` | Creates a folder |
| `share_note` | Shares a note, with read or write permission |
| `unshare_note` | Removes one person's share of a note |

The tools steer apps to `append_to_note` for adding to a note, and to HTML for editing a formatted note. For example: "Summarize the results of run\_3f2b… and add them to my Round 3 screening note." See the [tools reference](https://docs.revilico.bio/developers/mcp/tools.md#notes) for each tool's arguments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.