REST API reference

Team notes

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), 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. Reader comments are a separate resource: see Comments. 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. 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). 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). 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). Wait for the seconds in Retry-After.

Was this article helpful?