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 |
|---|---|---|
| List the notes on an article. | Any API key with Team notes. OAuth: |
| Start a note on a passage of the article. | Read & write key with Team notes. OAuth: |
| Reply to a note. | Read & write key with Team notes. OAuth: |
| Resolve a note. | Read & write key with Team notes. OAuth: |
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 Forbiddenwith the codeinsufficient_scope.OAuth apps get
notes.readandnotes.writeonly when they ask for these scopes and the person connecting the app approves them (see Scopes).content.readandcontent.writedon'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
403with the codenotes_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 |
|---|---|---|
| integer | The note's ID. |
| integer | The article the note is on. |
| integer or null |
|
| string | The article language the note was written in, for example |
| string | The text, as plain text. |
| object |
|
| object or null |
|
| string or null | The API key or OAuth app the note or reply came through, by name. |
| boolean |
|
| string | ISO 8601 in UTC, for example |
| array | On a note: its replies, oldest first, each a note object without |
| object |
|
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
/v1/articles/{articleId}/notesList the open team notes on an article, oldest first, each with its replies and the passage it is about.
Parameter | Type | Description |
|---|---|---|
| 1 or 0 | Default |
| 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
/v1/articles/{articleId}/notesStart 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 |
|---|---|---|
| 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. |
| string | Required. Plain text, 1 to 5000 characters. |
| 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
422with the codenote_quote_not_found. If it occurs more than once, the code isnote_quote_ambiguousandoccurrencessays 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.highlightedisfalse).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 Createdwith the new thread innote. Sending the same request twice adds two notes.
Reply to a note
/v1/articles/{articleId}/notes/{noteId}/repliesReply to a note. The response is the whole thread: the note with all its replies, yours last.
Field | Type | Description |
|---|---|---|
| string | Required. Plain text, 1 to 5000 characters. The field is |
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
404with "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
/v1/articles/{articleId}/notes/{noteId}/resolveResolve 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 |
|---|---|---|
| array | Up to 20 notes, each |
| object |
|
langon a note may be left out only when the request writes one language's content; a staged write always does. Otherwise the API answers422 note_lang_required. A note for a language the request doesn't write is422 note_locale_not_written: usePOST /v1/articles/{articleId}/notesfor 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 andannotate_changeshighlights the rest of the change. If the notes quote every change in a language, the request is refused with422 annotate_changes_covered: leaveannotate_changesout, 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 withannotate_changesone entry per language:lang,status(annotatedorskipped),note_id,highlighted,passages,unplaced_passagesand, when there is no highlight or the language was skipped, areason:unchanged,nothing_to_highlight,not_located(a changed passage couldn't be pinned to one place) ortoo_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 |
|---|---|
| The key or token is missing or not valid: |
|
|
| "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. |
| A parameter or field is not valid: |
| Over the rate limit (see Rate limits). Wait for the seconds in |