# Notes API

The Notes API lets developers and integration partners create, read, update and delete Note entities in epilot.

[[API Docs](/api/notes)] [[SDK](https://www.npmjs.com/package/@epilot/notes-client)]

The Notes API lets developers and integration partners create, read, update, and delete Note entities.

## Getting Notes by Context

Use the [`getNotesByContext`](/api/notes#tag/Notes/operation/getNotesByContext) operation to retrieve all notes associated with an entity.

```
GET /v1/notes/{entity_id}
```

### Non-Entity Contexts

Filter notes by non-entity contexts such as `workflow_execution` or `workflow_task` using the `contexts` query parameter:

```
GET /v1/notes/{entity_id}?contexts[]={"type":"workflow_execution","id":"zio6qcaduot"}
```

> **Note: URL-encode the `contexts` parameter values using [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).**

## Creating and Updating Notes

Create a note with [`createNote`](/api/notes#tag/Notes/operation/createNote). Update an existing note with [`updateNote`](/api/notes#tag/Notes/operation/updateNote) or [`patchNote`](/api/notes#tag/Notes/operation/patchNote). These operations accept all attributes defined on the Note entity schema, plus a `content` attribute containing stringified HTML.

### Content Formatting Rules

Note content is normalized -- inline style attributes are stripped. Use standard HTML tags for formatting:

- Wrap all content in a `<body>` tag
- `<p>` for paragraphs
  - Use `<span>` with the `epilot360-comment-user-id` attribute to mention users
- `<h1>` to `<h3>` for headings (max 3 levels)
- `<ol>` / `<ul>` with `<li>` for lists
- `<a href="...">` for links
- `<strong>` / `<b>` for bold, `<em>` / `<i>` for italic, `<u>` for underline

```json title="createNote request body"
{
  "entity_id": "4e9f4d7a-f5d8-4f0d-b8d6-d1b1d5f1f2f3",
  "content": "<body><p>Hello from epilot</p></body>"
}
```

## Pinning Notes

Use [`pinNote`](/api/notes#tag/Notes/operation/pinNote) to pin a note to the top of the Notes tab. Pass the Note entity ID as a path parameter.

## Deleting Notes

Use [`deleteNote`](/api/notes#tag/Notes/operation/deleteNote) to delete a note. Pass the Note entity ID as a path parameter.

> **Danger: Deleting a note that has comments also deletes all comment Note entities in that thread.**