Labels

Update a label or group

Requires the Labels: Update permission (on by default for admins and members). Send at least one field; an empty body returns 400. Only the fields you send change.

Request rules

  • An archived label cannot be edited: restore it first (400 "Restore this label before editing it.").
  • A group has no colour and cannot be placed inside another group (400).
  • parentId moves a label into a group; null moves it to the top level. A label cannot be its own group (400).

Errors

  • 400 for the rules above or a field that fails validation.
  • 403 without the permission.
  • 404 when the label or the new parent group does not exist.
  • 409 when the new name is already used by an active label under the same parent.
put/labels/{labelId}

Request

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

Path parameters

labelIdstring required

Id of the label or 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.

Request body

namestring

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.

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 a group to move the label into, or null to move it to the top level. 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.