Skip to content

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.

id
required
string format: uuid

The post’s id.

object
title

A title for the sketch, stored trimmed as the comment’s body. Leave it out for an untitled sketch.

string
<= 200 characters
content
required

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

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.

integer
>= 1
source_h
required

The height of the canvas the sketch was drawn on, in CSS pixels.

integer
>= 1
image_hash

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.

string
nullable
canvas_color

The background colour behind the layers, as a hex string. When it’s missing, the web app paints white (#ffffff).

string
layers
required

The layers, from bottom to top. Each has its own visibility, opacity, lock and items.

Array<object>
>= 1 items <= 32 items
object
id
required

An identifier for the layer, unique within the sketch. The web app uses a random UUID.

string
name

The layer’s name, if it has one.

string
visible

Whether the layer is drawn.

boolean
default: true
opacity

The layer’s opacity, from 0 (invisible) to 1.

number
default: 1 <= 1
locked

When true, the layer can’t be edited in the web app; it can still be shown or hidden.

boolean
items
required

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.

Array<object>
object
kind
required

What the item is. The fields that apply depend on it.

string
Allowed values: stroke shape text image
tool

For a stroke, the brush; for a shape, the shape.

string
Allowed values: pen marker highlighter eraser line arrow rect rounded-rect ellipse triangle right-triangle diamond pentagon hexagon star heart callout-rect callout-oval
color

The item’s colour. Strokes and text use only this; shapes use strokeColor and fillColor when they’re set, and this otherwise.

string
strokeColor

A shape’s outline colour. color is used when it’s missing.

string
fillColor

A shape’s fill colour. color is used when it’s missing.

string
width

The line width of a stroke or a shape’s outline, in canvas pixels.

number
<= 200
opacity

The item’s opacity, from 0 to 1.

number
default: 1 <= 1
points

A stroke’s points in canvas pixels, each [x, y] or [x, y, pressure].

Array<Array<number>>
x

The horizontal position of a shape, text or image box, in canvas pixels.

number
y

The vertical position of a shape, text or image box, in canvas pixels.

number
w

The width of a shape, text or image box, in canvas pixels.

number
h

The height of a shape, text or image box, in canvas pixels.

number
fill

A shape’s fill opacity, from 0 (outline only) to 1 (solid).

number
<= 1
body

A text item’s text.

string
<= 10000 characters
fontSize

A text item’s font size, in canvas pixels.

number
>= 8 <= 256
align

How a text item’s lines are aligned.

string
default: left
Allowed values: left center right
bold

Whether a text item is bold.

boolean
italic

Whether a text item is italic.

boolean
src

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.

string
rotation

The box’s clockwise rotation about its centre, in degrees.

number
0

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