Save a whiteboard sketch on a post
POST /posts/{id}/whiteboards
Saves a sketch on the post as a top-level comment with
annotation_type set to whiteboard: content becomes its
annotation_data and the trimmed title its body, which is empty
when there’s no title. 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; nothing else about the shape of content is checked. Then
you need to be signed in (401) and hold posts.comment (part of the
Base role) or system.admin (403); there’s no separate capability
for sketches. You then need to be able to read the post: it’s the
same read check GET /posts/{id} makes, without the mature
settings, and a post you can’t read answers 404, as one that doesn’t
exist or is deleted does. The post’s comments_enabled setting
isn’t checked, so a sketch can be saved on a post that doesn’t take
comments.
content is read into the fields described below and stored as they
come out: anything else you send is dropped, and positions, sizes,
point values and the other fractional drawing settings are held in
single precision, so they can be rounded; source_w and source_h
are whole numbers and aren’t affected. Only the drawing data is
stored; no picture of it is made. The sketch is listed with the
post’s sketches and in its comment thread, where others can reply to
it.
The sketch and its activity are saved together. After that, the
server tries to give the post’s author an in-app notice, as for a
comment; none is created if the sketch is theirs, if one of you has
blocked the other, if their notice settings for comments leave out
in-app notices, or if creating it fails, which is only logged. It
isn’t emailed. The post’s comment_count goes up by one, but its
cached details aren’t refreshed, so other reads can show the old
count for a while.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The post’s id.
Request Body required
Section titled “Request Body required ”object
A title for the sketch, stored trimmed as the comment’s body. Leave it out for an untitled sketch.
A sketch as drawing data: the size of the canvas it was drawn on and its layers of items, from bottom to top. The web app redraws the sketch from this; no picture of it is stored.
object
The width of the canvas the sketch was drawn on, in CSS pixels. Positions and sizes in the items are in this canvas’s pixels, so a viewer can scale the sketch to fit.
The height of the canvas the sketch was drawn on, in CSS pixels.
Meant for the hash of a stored picture of the sketch. Nothing creates one at present and the web app doesn’t send it, so it’s normally left out.
The background colour behind the layers, as a hex string. When it’s
missing, the web app paints white (#ffffff).
The layers, from bottom to top. Each has its own visibility, opacity, lock and items.
object
An identifier for the layer, unique within the sketch. The web app uses a random UUID.
The layer’s name, if it has one.
Whether the layer is drawn.
The layer’s opacity, from 0 (invisible) to 1.
When true, the layer can’t be edited in the web app; it can still be shown or hidden.
What’s drawn on the layer, in drawing order. kind says what each
item is: a brush stroke, a shape, a text label or an image.
The other fields apply according to it.
object
What the item is. The fields that apply depend on it.
For a stroke, the brush; for a shape, the shape.
The item’s colour. Strokes and text use only this; shapes use strokeColor and fillColor when they’re set, and this otherwise.
A shape’s outline colour. color is used when it’s missing.
A shape’s fill colour. color is used when it’s missing.
The line width of a stroke or a shape’s outline, in canvas pixels.
The item’s opacity, from 0 to 1.
A stroke’s points in canvas pixels, each [x, y] or [x, y, pressure].
The horizontal position of a shape, text or image box, in canvas pixels.
The vertical position of a shape, text or image box, in canvas pixels.
The width of a shape, text or image box, in canvas pixels.
The height of a shape, text or image box, in canvas pixels.
A shape’s fill opacity, from 0 (outline only) to 1 (solid).
A text item’s text.
A text item’s font size, in canvas pixels.
How a text item’s lines are aligned.
Whether a text item is bold.
Whether a text item is italic.
An image item’s picture, as a data: URL or a web address. Pictures
pasted in the web app are stored inside the sketch as data: URLs.
The box’s clockwise rotation about its centre, in degrees.
Responses
Section titled “ Responses ”The sketch, 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
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