Labels

Create a label or group

Requires the Labels: Create permission (on by default for admins and members).

Request rules

  • Send isGroup: true to create a group. A group cannot have color or parentId; sending either returns 400.
  • parentId must be the labelId of an active group in your company. A missing group returns 404 "Parent group not found."; a label that is not a group returns 400 "A label can only be placed inside a group."
  • color defaults to #6366f1 when you leave it out.
  • sortOrder defaults to 0.

Errors

  • 400 when a field fails validation or the parent is not a group.
  • 403 without the permission.
  • 404 when the parent group does not exist.
  • 409 when an active label with the same name already exists under the same parent. Names are compared ignoring case, after trimming and collapsing spaces.
post/labels

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/labels
  • Auth: API key in header x-speakai-key and API key in header x-access-token

Request body

namestring required

Name of the label or group. Trimmed, then 1 to 80 characters. Repeated spaces are collapsed to one before saving. Names are unique among active labels with the same parent, compared without regard to case, so a duplicate returns 409.

isGroupboolean

true to create a group instead of a label. Defaults to false.

descriptionstring

What the label means, shown to people choosing it. Up to 500 characters after trimming. An empty string is accepted.

colorstring

Colour as six-digit hex, #rrggbb (pattern ^#[0-9a-fA-F]{6}$). Stored in lower case. Not allowed on a group.

parentIdstring nullable

labelId of the group to put the label in. null or left out for the top level. Not allowed on a group. Trimmed, then 1 to 64 characters from A-Z, a-z, 0-9, _ and - (pattern ^[A-Za-z0-9_-]{1,64}$). Anything else returns 400.

sortOrderinteger

Position among its siblings, lowest first. Integer from 0 to 1,000,000. Labels with the same value are ordered by name.

Example request

{
  "color": "#22c55e"
}

Response

Success

status'success'

success on every 2xx response.

Changes

No recorded changes to this operation across all 2 revisions of this API.