# Team notes

_Category: REST API reference_

Team notes are the private notes your team leaves on an article in the editor: a note on a highlighted passage, and the replies under it. Readers never see them. With the API, an integration or an AI agent can read the open notes on an article, answer them and resolve them, so feedback your team writes on a draft reaches the tool that revises it. It works the other way too: a tool that changes an article can leave a note on the passage it changed, with its reason, so a reviewer finds both in place.

A typical loop: the agent reads the open notes, revises the article without touching the live version (see [Staged changes and versions](https://developers.helpcenter.io/content/staged-changes-api)), replies to each note with what it changed, and resolves the notes it has dealt with. When it changes text nobody asked about, it leaves a note there saying why. A person still reviews and publishes.

Team notes are available on every plan. To see how your team writes them, see [Leave notes for your team](https://self.helpcenter.io/content/team-notes). Reader comments are a separate resource: see [Comments](https://developers.helpcenter.io/content/comments-api). Internal notes, the blocks your team types into the article text, have no endpoint, and article content you fetch through the API leaves them out.

## Endpoints

| Method and path | What it does | Access |
| --- | --- | --- |
| `GET /v1/articles/{articleId}/notes` | List the notes on an article. | Any API key with Team notes. OAuth: `notes.read` |
| `POST /v1/articles/{articleId}/notes` | Start a note on a passage of the article. | Read & write key with Team notes. OAuth: `notes.write` |
| `POST /v1/articles/{articleId}/notes/{noteId}/replies` | Reply to a note. | Read & write key with Team notes. OAuth: `notes.write` |
| `POST /v1/articles/{articleId}/notes/{noteId}/resolve` | Resolve a note. | Read & write key with Team notes. OAuth: `notes.write` |

To leave notes in the same request that changes the text, send `notes` or `annotate_changes` with the write: see [Notes on a content write](https://developers.helpcenter.io/content/team-notes-api#notes-on-a-content-write). There is no endpoint to edit or delete a note.

## Get access

Access to team notes is granted separately from access to your content, and checked twice on every request.

- **The key must be created with Team notes.** When you create the key, turn on **Allow access to editorial notes** under **Team notes** (see [Create an API key](https://self.helpcenter.io/content/create-an-api-key)). A **Read only** key can then read notes; a **Read & write** key can also start notes, reply and resolve. An existing key can't be given access: create a new one. Without it, the API answers `403 Forbidden` with the code `insufficient_scope`.
- **OAuth apps** get `notes.read` and `notes.write` only when they ask for these scopes and the person connecting the app approves them (see [Scopes](https://developers.helpcenter.io/content/scopes)). `content.read` and `content.write` don't include them.
- **The person behind the credential must still be on the team.** Every request checks that the team member who created the key, or who approved the app, can open team notes on this help center in the dashboard: an Owner, Admin, Editor or Translator. If they left the team or lost that role, the API answers `403` with the code `notes_forbidden`, and a new key from a current team member fixes it.
- **Private articles stay private.** If that person can't open the article in the dashboard, because it is private and not shared with them or it sits in a private category they are not a member of, its notes answer `404 Not Found`. So do articles in the Trash.

## The note object

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | The note's ID. |
| `article_id` | integer | The article the note is on. |
| `parent_id` | integer or null | `null` for a note, the note's `id` for a reply. |
| `lang` | string | The article language the note was written in, for example `en`. Replies take the note's language. |
| `note` | string | The text, as plain text. |
| `anchor` | object | `quote` is the passage that was highlighted when the note was written, and `mark_id` the highlight's ID in the article. Use `quote` to find the text the note is about. `highlighted` is `true` while the live article or its staged copy still carries the highlight; it turns `false` when someone rewrites or deletes the passage (the note stays, and `quote` still says what it was about). `mark_id` and `quote` are `null` on replies. |
| `author` | object or null | `id`, `name` and `avatar` (a URL, or `null`) of the team member. Never an email address. |
| `via` | string or null | The API key or OAuth app the note or reply came through, by name. `null` for notes written in the dashboard. The editor shows it beside the author. |
| `resolved` | boolean | `true` once the note is resolved. |
| `created_at`, `updated_at` | string | ISO 8601 in UTC, for example `2026-09-30T08:15:56+00:00`. |
| `replies` | array | On a note: its replies, oldest first, each a note object without `replies`. |
| `_links` | object | `reply` and `resolve`, each with the `method` and `url` to call. |

Replies carry `_links` too, but you reply to and resolve the note, not a reply: use the links of the note at the top of the thread. A reply's own links answer `404`.

## List the notes on an article

GET`/v1/articles/{articleId}/notes`

List the open team notes on an article, oldest first, each with its replies and the passage it is about.

| Parameter | Type | Description |
| --- | --- | --- |
| `include_resolved` | 1 or 0 | Default `0`: open notes only. `1` adds resolved notes, with their replies. `true` and `false` are refused with `422 Unprocessable Entity`. |
| `lang` | string | Only notes in this language. It is matched exactly and not checked against your languages, so a typo returns an empty list. |

Notes come oldest first, with every note on the article in one response. `meta.threads_count` is the number of notes returned, `meta.open_count` how many of them are open, and `meta.includes_resolved` echoes your choice. The top-level `article.title` is an object with every language of the title.

## Start a note on a passage

POST`/v1/articles/{articleId}/notes`

Start a note on a passage already in the article. Quote the passage as plain text; the API highlights it where it occurs exactly once.

| Field | Type | Description |
| --- | --- | --- |
| `quote` | string | Required, up to 5000 characters. The passage the note is about, as plain text exactly as it reads in the article: not Markdown, not HTML. Quote enough of it to occur only once. |
| `note` | string | Required. Plain text, 1 to 5000 characters. |
| `lang` | string | The language whose text the passage is in, one of your help center's languages. Defaults to your default language. |

- You don't name a highlight. The API looks for the passage in that language's staged copy, if there is one, and in the live article, and highlights it in every copy that holds it exactly once.
- The passage is matched on its text alone, so spaces, line breaks and HTML entities don't matter, and it may run across bold text, links and paragraphs.
- If the passage is in neither copy, the API answers `422` with the code `note_quote_not_found`. If it occurs more than once, the code is `note_quote_ambiguous` and `occurrences` says how often: quote more of the sentence around it. Either way, nothing is written.
- A passage carries one note's highlight. Text another open note already highlights is left out of the new highlight, and if another note covers all of it, the note is created without one (`anchor.highlighted` is `false`).
- Adding a note isn't an edit: no new version, no change to the article's last-edited time, nothing readers see. Your team sees it in the editor, on the passage and in the Comments drawer.
- The note is signed like a reply. The response is `201 Created` with the new thread in `note`. Sending the same request twice adds two notes.

## Reply to a note

POST`/v1/articles/{articleId}/notes/{noteId}/replies`

Reply to a note. The response is the whole thread: the note with all its replies, yours last.

| Field | Type | Description |
| --- | --- | --- |
| `note` | string | Required. Plain text, 1 to 5000 characters. The field is `note`, not `comment`: a body with `comment` is refused with "A note body is required." |

- The reply is signed by the team member who created the key, or who approved the app, and takes the note's language.
- The response is the whole thread: the note, with every reply and yours last.
- Replying sends no email and doesn't change the article.
- Sending the same request twice adds two replies.
- A resolved note answers `404` with "That note is resolved. Re-open it in the dashboard to continue the thread." A resolved note can't be reopened, in the dashboard or over the API, so ask your team to start a new note in the editor.

## Resolve a note

POST`/v1/articles/{articleId}/notes/{noteId}/resolve`

Resolve a note and all its replies. There is no request body, and it cannot be undone.

Resolving closes the note and all its replies. Resolving a note that is already resolved answers `200` with "That note was already resolved.", so a retry is safe. It can't be undone, and resolved notes stay readable only through this API, with `include_resolved=1`.

Resolving also removes the note's highlight from the article, live and staged, as resolving in the editor does, unless another open note shares it. Nothing readers see changes.

## Notes on a content write

`PATCH /v1/articles/{id}` and `PATCH /v1/articles/{id}/staged` take two more optional fields, so an integration can explain a change in the request that makes it. Both need what the notes endpoints need on top of what the write needs: a key with Team notes (OAuth: `notes.write`), and a person behind it who can still open team notes. Without them, the write is refused with the same `403` codes and nothing is written.

| Field | Type | Description |
| --- | --- | --- |
| `notes` | array | Up to 20 notes, each `{"quote", "note", "lang"}`. Each quote must occur exactly once in the **new** text of its language, as the write stores it (Markdown converted, unsafe HTML removed). A passage that is only in the text being replaced can't be noted. |
| `annotate_changes` | object | `{"note": "..."}`. One note for each language whose content the request changes, highlighting what changed: every added block whole, and in each edited block the text from its first changed word to its last. |

- `lang` on a note may be left out only when the request writes one language's content; a staged write always does. Otherwise the API answers `422 note_lang_required`. A note for a language the request doesn't write is `422 note_locale_not_written`: use `POST /v1/articles/{articleId}/notes` for text already in the article.
- "Changed" is measured against the text the write replaces: the live text for `PATCH /v1/articles/{id}`, and the previous staged text (the live text on the first staged save) for `/staged`. A language whose content didn't change gets no note. A change that only removes text, or has no text, such as an image, gets a note without a highlight.
- Two notes in one request can't quote overlapping text (`422 note_quotes_overlap`). With both fields, each note keeps its quote and `annotate_changes` highlights the rest of the change. If the notes quote every change in a language, the request is refused with `422 annotate_changes_covered`: leave `annotate_changes` out, or quote less.
- **All or nothing.** If any quote is refused, nothing is written: no content, no staged version, no new version in the history, no note, and no image is re-hosted.
- The response adds `notes`, every note the request created, and with `annotate_changes` one entry per language: `lang`, `status` (`annotated` or `skipped`), `note_id`, `highlighted`, `passages`, `unplaced_passages` and, when there is no highlight or the language was skipped, a `reason`: `unchanged`, `nothing_to_highlight`, `not_located` (a changed passage couldn't be pinned to one place) or `too_long` (the article is too large to compare word by word).
- On `/staged`, the highlights go into the staged copy, and publishing carries them live.

Article reads never include highlights, so the content you write back has none. That doesn't erase them: an open note's highlight is carried over onto your new text wherever its passage still stands.

## Errors

| Status | When |
| --- | --- |
| `401 Unauthorized` | The key or token is missing or not valid: `{"status": "unauthorized"}`. |
| `403 Forbidden` | `role_forbidden` (OAuth): the person who approved the app has a role that can't open team notes. `insufficient_scope`: the key was created without Team notes, a Read only key tried to start, reply to or resolve a note, or an OAuth token lacks `notes.read` or `notes.write`. `notes_forbidden`: the person behind the credential can no longer open team notes on this help center. |
| `404 Not Found` | "Article not found." for an article you can't reach, "No such note on this article." for an unknown note or a reply's ID, or "That note is resolved." when you reply to a resolved note. |
| `422 Unprocessable Entity` | A parameter or field is not valid: `errors` names it. Or a quote was refused, with a `code` (`note_quote_not_found`, `note_quote_ambiguous`, `note_lang_required`, `note_locale_not_written`, `note_quotes_overlap`, `annotate_changes_covered`) and `field` naming the quote at fault. Nothing was written. |
| `429 Too Many Requests` | Over the rate limit (see [Rate limits](https://developers.helpcenter.io/content/rate-limits)). Wait for the seconds in `Retry-After`. |

## Related

- [Comments](https://developers.helpcenter.io/content/comments-api)
- [API keys](https://developers.helpcenter.io/content/api-keys)
- [Scopes](https://developers.helpcenter.io/content/scopes)
