Skip to content

Annotate a range in a text asset

POST
/assets/{id}/text-annotations

Adds a text annotation to the asset: a highlight, strikethrough, underline, comment or note over a range of lines and columns. It’s saved as a top-level comment with annotation_type set to text-range, and the new comment is returned as saved.

A request body that isn’t valid JSON, or that gives a field a value of the wrong type, is refused with 400 before anything else is checked; missing fields and the schema’s limits aren’t checked. Then you need to be signed in (401) and hold posts.comment (part of the Base role) or system.admin (403). Last, you 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, as for an asset that doesn’t exist or is deleted.

anchor becomes the comment’s annotation_data and body its text. The range is stored as given: the server doesn’t check it against the file, check that it’s in order, or require the asset to have a file, and it doesn’t record which version of the file the range refers to, so a range can point at the wrong text after the file changes. Required anchor fields you don’t send are stored as empty or zero, resolved is left out unless you send it, and fields the anchor doesn’t define are dropped. body is stored exactly as sent, with no trimming, and isn’t turned into HTML.

Nothing else happens: no activity is recorded, nobody is notified and @-mentions aren’t processed. Sending the same request twice saves two annotations.

id
required
string format: uuid

The asset’s id.

object
body

The commentary, stored exactly as sent. Leave it out, or send an empty string, for a plain highlight.

string
<= 8000 characters
anchor
required

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

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.

string
Allowed values: highlight strikethrough underline comment note
color
required

The colour to show it in, as a hex string such as #fef08a. The server doesn’t check the value.

string
<= 16 characters
start_line
required

The line the range starts on, counting from 1.

integer
>= 1
start_col
required

Where the range starts within that line, counting from 0.

integer
end_line
required

The line the range ends on, counting from 1.

integer
>= 1
end_col
required

Where the range ends within that line, counting from 0; the range stops just before it.

integer
resolved

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.

boolean

The annotation as saved.

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
id
required
string format: uuid
target_kind
required
string
Allowed values: post asset collection
target_id
required
string format: uuid
parent_id
string format: uuid
nullable
root_id
required
string format: uuid
depth
required
integer
author_user_ref

The local user who wrote the comment. Left out for comments received from another instance.

integer format: int64
nullable
body
required
string
body_html
required

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.

string
annotation_type
string
nullable
Allowed values: point rect timestamp frame whiteboard text-range
annotation_data
object
key
additional properties
any
like_count
required
integer format: int64
edited_at
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
peer_id

The paired instance a received comment came from. Left out for comments written on this instance.

string format: uuid
nullable
actor_uri

The author’s address on their home instance, for example https://studio-b.example/users/bob. Left out for comments written on this instance.

string
nullable
display_name

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.

string
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed