Update a text annotation
PATCH /text-annotations/{id}
Changes a text annotation’s body, its anchor, or both, and
returns it. A field you leave out, or send as null, stays as it
is. anchor is replaced as a whole, so send every field you want to
keep: missing required fields become empty or zero, and resolved
is dropped if left out.
You need to be signed in. The annotation must exist and not be
deleted (404) and must be a text annotation (400 otherwise). You
then need to be allowed to read the asset’s content, not just see it
listed: you’re its owner, it’s public, it’s a team asset of a
team you belong to, or you hold content.read.all or
system.admin. Mature assets also follow the mature settings,
except for their owner and system.admin. Otherwise the answer is
404. Last, you need to be the annotation’s author or hold
comments.delete.any or system.admin (403 otherwise). Authors
need no capability to edit their own annotations, and a moderator
who can’t read the asset can’t edit its annotations.
Sending body, even unchanged, sets edited_at, and an empty
string clears the text. Every successful request sets updated_at,
including one that changes nothing. There’s no version check, and
the stored anchor is written back on every update, so two people
editing one annotation can overwrite each other’s changes, including
a range someone else changed while you edited only the text.
No activity is recorded and nobody is notified. To delete an
annotation, use DELETE /comments/{id}.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The annotation’s id.
Request Body required
Section titled “Request Body required ”Send only what you’re changing. anchor replaces the whole stored
anchor; it isn’t merged field by field.
object
The new commentary, stored exactly as sent. An empty string clears it; leave it out to keep it.
Where an annotation sits in the file and how it looks. Lines count from 1 and columns from 0, as positions within the line in the web app’s editor (UTF-16 code units). A range whose start equals its end marks one position, which the web app uses for notes. The server stores these values as given and doesn’t check them.
object
How the range is shown. comment and note usually carry text in
the comment’s body; the other styles usually don’t, but any style
can.
The colour to show it in, as a hex string such as #fef08a. The
server doesn’t check the value.
The line the range starts on, counting from 1.
Where the range starts within that line, counting from 0.
The line the range ends on, counting from 1.
Where the range ends within that line, counting from 0; the range stops just before it.
Whether the annotation is marked resolved. Resolving doesn’t delete it or remove it from the list; the web app hides resolved annotations unless you choose to show them.
Responses
Section titled “ Responses ”The annotation as updated.
One comment. A reply has parent_id; root_id is the first comment
in its thread and depth counts how far down the thread it is (0
for a top-level comment). Annotations also carry annotation_type
and annotation_data.
A comment written on this instance has author_user_ref; one
received from a paired instance has peer_id and actor_uri
instead. Fields with no value are left out.
object
The local user who wrote the comment. Left out for comments received from another instance.
Normally an empty string: no endpoint except the seed endpoint stores HTML here, comments from other instances don’t carry any, and the web app shows body as plain text. The seed endpoint stores its value unchecked, so don’t display this field as HTML.
object
The paired instance a received comment came from. Left out for comments written on this instance.
The author’s address on their home instance, for example https://studio-b.example/users/bob. Left out for comments written on this instance.
The remote author’s display name. It’s often left out, even for
received comments; when it is, show the host and user name from
actor_uri instead.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed