Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Using TypeScript? Check out our GraphQL SDK for a fully typed client.
Label types define the labels available in your workspace. Each label type has a name, icon, colour, and optionally a description, parent label type and external ID. When you want to stop a label being available, archive its label type rather than deleting it — this preserves the historical record on existing threads. The mutations below all require the following permissions:
  • labelType:create
  • labelType:edit
The read queries require:
  • labelType:read

​
Get label types

Use labelTypes to fetch the full list of label types in your workspace. By default this includes archived label types — pass filters: { isArchived: false } to exclude them.
Query
query getLabelTypes($first: Int = 50, $after: String) {
  labelTypes(filters: { isArchived: false }, first: $first, after: $after) {
    edges {
      node {
        id
        externalId
        name
        icon
        color
        type
        description
        parentLabelType {
          id
          name
        }
        isArchived
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Variables
{
  "first": 50
}

​
Get a label type by ID

Query
query getLabelType($labelTypeId: ID!) {
  labelType(labelTypeId: $labelTypeId) {
    id
    externalId
    name
    icon
    color
    type
    description
    isArchived
  }
}
Variables
{
  "labelTypeId": "lt_01HB924PME9C0YWKW1N4AK3BZA"
}

​
Get a label type by external ID

If you store your own identifier on label types via externalId, you can look them up by that value. External IDs are unique within a workspace.
Query
query getLabelTypeByExternalId($externalId: ID!) {
  labelTypeByExternalId(externalId: $externalId) {
    id
    externalId
    name
    icon
    color
    type
    description
    isArchived
  }
}
Variables
{
  "externalId": "billing"
}

​
Create a label type

Mutation
mutation createLabelType($input: CreateLabelTypeInput!) {
  createLabelType(input: $input) {
    labelType {
      id
      externalId
      name
      icon
      color
      type
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "name": "Billing",
    "icon": "credit-card",
    "color": "#FFB400",
    "description": "Billing and invoicing questions",
    "externalId": "billing"
  }
}

​
Update a label type

Updates use field-level wrapper inputs — to change a field pass { "value": ... }; to leave a field untouched omit it entirely.
Mutation
mutation updateLabelType($input: UpdateLabelTypeInput!) {
  updateLabelType(input: $input) {
    labelType {
      id
      name
      icon
      color
      description
      externalId
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "labelTypeId": "lt_01HB924PME9C0YWKW1N4AK3BZA",
    "name": { "value": "Billing & invoicing" },
    "description": { "value": "Questions about billing, invoices and payments." }
  }
}

​
Archive a label type

Archived label types stay attached to existing threads but cannot be added to new threads. Attempting to call addLabels with an archived label type returns the error code cannot_add_label_using_archived_label_type.
Mutation
mutation archiveLabelType($input: ArchiveLabelTypeInput!) {
  archiveLabelType(input: $input) {
    labelType {
      id
      name
      isArchived
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "labelTypeId": "lt_01HB924PME9C0YWKW1N4AK3BZA"
  }
}

​
Unarchive a label type

Mutation
mutation unarchiveLabelType($input: UnarchiveLabelTypeInput!) {
  unarchiveLabelType(input: $input) {
    labelType {
      id
      name
      isArchived
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "labelTypeId": "lt_01HB924PME9C0YWKW1N4AK3BZA"
  }
}