lt.roles

lt.roles manages roles. A role is a queue worked by its members: it owns the versioned resolver form, the list page layout, the Operations targets and the escalation chains to other roles. See Identity and Forms.

Work-surface scope

Each member assignment carries two scope axes that set how much of the queue the member touches:

Axis	Values	Governs
read_scope	self, all (default all)	Search: which escalations the member sees
write_scope	none, self, all (default all)	Claim, resolve and cancel: which escalations the member may act on

self means rows assigned to the member; all means the whole queue. Write is a subset of read: write_scope=all requires read_scope=all. admin and superadmin ignore scope and act on the whole queue. Scope is set when a role is assigned, through lt.users.addRole or lt.users.create.

RoleDetail

listWithDetails and update return RoleDetail objects:

interface RoleDetail {
  role: string;
  title: string | null;
  description: string | null;
  form_schema: Record<string, any> | null;
  metadata_schema: Record<string, any> | null;
  properties: Record<string, any>;
  ops_visible: boolean;
  ops_home_default: boolean;
  parent_role: string | null;
  sla_minutes: number | null;
  target_per_hour: number | null;
  worker_count: number | null;
  priority_threshold_minutes: number | null;
  priority_facet: string | null;
  entity_facet: string | null;
  entity_state_source: 'role' | 'subtype';
  current_schema_version: number | null;
  list_schema: Record<string, any> | null;
  current_list_schema_version: number | null;
  enforce_schema: boolean;
  default_pins: { label: string; url: string; badge?: boolean }[] | null;
  portals: { key: string; label: string; rows: { label: string; url: string; badge?: boolean }[][]; counts?: { label: string; url: string; blurb?: string }[] }[] | null;
  upstream_roles: string[];
  user_count: number;
  chain_count: number;
  workflow_count: number;
}

Field	Description
role	Unique role key
title	Display name in the dashboard
description	Short description of the role’s purpose
form_schema	JSON Schema for the resolve form. metadata.form_schema on a row overrides it
metadata_schema	JSON Schema for escalation metadata; drives validation and key autocomplete
properties	Free user-owned bag of configuration
ops_visible	true shows the role as a station on the Operations view
ops_home_default	Makes this role’s sequence the home Pace Board’s default segment
parent_role	Parent role in the process graph; orders the pace chart
sla_minutes	SLA target in minutes; the default age threshold for priority_count
target_per_hour	Throughput target used for throughput_pct
worker_count	Station capacity
priority_threshold_minutes	Max age before a pending unclaimed row counts toward priority_count; falls back to sla_minutes
priority_facet	Metadata key holding the age origin as an ISO 8601 UTC timestamp (for example received_at); falls back to created_at
entity_facet	Metadata key identifying the entity that moves through this role (for example serialNumber)
entity_state_source	How the role names the entity’s states: role (the station is the state) or subtype
enforce_schema	true validates resolver payloads against the role’s form on the server
user_count	Users assigned to the role
chain_count	Escalation chain links from this role
workflow_count	Registered workflows that target this role

See Analytics for entity_facet and Schema enforcement for enforce_schema.

list

const result = await lt.roles.list();

List every distinct role name.

Parameters: none.

Returns: LTApiResult<{ roles: string[] }>

Auth: Not required.

listWithDetails

const result = await lt.roles.listWithDetails();

List every role with full details.

Parameters: none.

Returns: LTApiResult<{ roles: RoleDetail[] }>

Auth: Not required.

create

const result = await lt.roles.create({ role: 'senior-reviewer' });

Create a role. The name is trimmed, lowercased and validated against ^[a-z][a-z0-9_-]*$.

Parameters

Field	Type	Required	Description
role	string	Yes	Role name: lowercase letters, numbers, hyphens and underscores, starting with a letter

Returns: LTApiResult<{ role: string }> with status 201.

Auth: Not required.

update

const result = await lt.roles.update({
  role: 'reviewer',
  title: 'Document Reviewer',
  ops_visible: true,
  sla_minutes: 30,
  target_per_hour: 20,
  worker_count: 4,
});

Update a role. Only the fields you pass change. Pass null to clear a nullable field. When the update changes form_schema or metadata_schema, the new pair is saved to the role’s version history and current_schema_version advances.

Parameters

Field	Type	Required	Description
role	string	Yes	Role key
title	string | null	No	Display name
description	string | null	No	Short description
form_schema	object | null	No	JSON Schema for the resolve form. Fields may carry x-lt-bind
metadata_schema	object | null	No	JSON Schema for escalation metadata
list_schema	object | null	No	Layout (x-lt-* markup) for the role’s escalation list page; versions independently of form_schema
default_pins	array | null	No	Pinned-view seeds for members: [{ label, url, badge? }] with dashboard-relative URLs. Members reorder or hide them in their own preferences (lt.me)
portals	array | null	No	Named portals [{ key, label, rows, counts? }]: 1 to 4 rows of 1 to 6 pin cells, rendered at /portal/<role>/<key>, with up to 8 count tiles
properties	object | null	No	Free user-owned bag
ops_visible	boolean	No	Show as a station on the Operations view
ops_home_default	boolean	No	Make this role’s sequence the home Pace Board default. Setting it clears the previous holder
parent_role	string | null	No	Parent role in the process graph
sla_minutes	number | null	No	SLA target in minutes
target_per_hour	number | null	No	Throughput target (items per hour)
worker_count	number | null	No	Station capacity (a whole number)
priority_threshold_minutes	number | null	No	Priority age threshold; falls back to sla_minutes
priority_facet	string | null	No	Metadata key for the priority age origin; falls back to created_at
entity_facet	string | null	No	Metadata key identifying the entity that moves through this role
entity_state_source	'role' | 'subtype' | null	No	How the role names entity states. null resets to role
enforce_schema	boolean	No	Turn server-side resolver validation on or off
upstream_roles	string[] | null	No	Replace the roles this station draws input from across other Operations sequences (omitted keeps it; null or [] clears). Separate from parent_role, which places the role in its own sequence
change_summary	string	No	Label recorded on the schema version snapshot when the update changes a schema

Returns: LTApiResult<RoleDetail>. 400 for a missing role or an invalid field value.

Auth: Not required in-process. Over HTTP the route requires a role manager (admin type, superadmin or the engineer role).

delete

const result = await lt.roles.delete({ role: 'old-role' });

Delete a role.

Parameters

Field	Type	Required	Description
role	string	Yes	Role to delete

Returns: LTApiResult<{ deleted: true }>. 409 when the role cannot be deleted (for example, it is still assigned to users).

Auth: Not required.

getSchema

const latest = await lt.roles.getSchema({ role: 'reviewer' });
const pinned = await lt.roles.getSchema({ role: 'reviewer', version: 3 });

Fetch a role’s form_schema and metadata_schema pair. With version, reads that immutable snapshot (the one an escalation pins through conditional’s schemaVersion). Without it, reads the latest schema and its version number. A missing version returns 404 and never falls back to another version.

Parameters

Field	Type	Required	Description
role	string	Yes	Role
version	number	No	Version pin (positive integer)

Returns: LTApiResult<RoleSchemaVersion>: { role, version, form_schema, metadata_schema, change_summary, created_at, latest_version }.

Auth: Not required.

listSchemaVersions

const result = await lt.roles.listSchemaVersions({ role: 'reviewer' });
// result.data.versions → [{ version, has_form_schema, has_metadata_schema, change_summary, created_at, is_current }, ...]

List a role’s schema version history, newest first.

Parameters

Field	Type	Required	Description
role	string	Yes	Role

Returns: LTApiResult<{ versions: RoleSchemaVersionSummary[] }>

Auth: Not required.

getEscalationChains

const result = await lt.roles.getEscalationChains();

List every escalation chain across all roles.

Parameters: none.

Returns: LTApiResult<{ chains: EscalationChain[] }>

Auth: Not required.

addEscalationChain

const result = await lt.roles.addEscalationChain({
  source_role: 'reviewer',
  target_role: 'senior-reviewer',
});

Add a chain link from one role to another.

Parameters

Field	Type	Required	Description
source_role	string	Yes	Role that escalates
target_role	string	Yes	Role that receives

Returns: LTApiResult<{ source_role, target_role }> with status 201.

Auth: Not required.

removeEscalationChain

const result = await lt.roles.removeEscalationChain({
  source_role: 'reviewer',
  target_role: 'senior-reviewer',
});

Remove a chain link between two roles.

Parameters

Field	Type	Required	Description
source_role	string	Yes	Role that escalates
target_role	string	Yes	Role that receives

Returns: LTApiResult<{ removed: true }>. 404 if not found.

Auth: Not required.

getEscalationTargets

const result = await lt.roles.getEscalationTargets({ role: 'reviewer' });

List the target roles for a source role.

Parameters

Field	Type	Required	Description
role	string	Yes	Source role

Returns: LTApiResult<{ targets: string[] }>

Auth: Not required.

replaceEscalationTargets

const result = await lt.roles.replaceEscalationTargets({
  role: 'reviewer',
  targets: ['senior-reviewer', 'team-lead'],
});

Replace every target of a role with a new set.

Parameters

Field	Type	Required	Description
role	string	Yes	Source role
targets	string[]	Yes	Target role names

Returns: LTApiResult<{ role, targets }>

Auth: Not required.