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.

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. 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

There is no endpoint to create, edit or delete a note. A note belongs to a passage your team highlights in the editor, so it starts there.

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 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

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

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.

Reply to a note

• 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

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 through the API doesn't change the article. When your team resolves a note in the editor, the editor also removes the highlight from the text; after an API resolve, the passage stays highlighted and the highlight no longer opens a note.

Errors

Related

• Comments

• API keys

• Scopes