Company roles

A company role is a named position in your organization’s org chart (for example “Service Manager”). Each role can have a training curriculum — the lessons and topics everyone in the role is expected to complete — and a set of members who currently hold it.

Note

These endpoints are available only to tokens whose user can read the org chart (the company-role.read permission). A token without it receives 403.

List company roles

GET /v1/company-roles

Lists the organization’s company roles, sorted alphabetically by name. Each result carries how many people hold the role and the role it reports to.

Query parameters

Parameter	Type	Notes
query	string	Case-insensitive match on the role name.
cursor	string	Pagination cursor from a previous response.
limit	number	1–100. Default 50.

Request

curl "https://api.mereon.ai/v1/company-roles?query=manager" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "id": "695690de-1c49-42c7-a416-b0d3bea29102",
      "name": "Service Manager",
      "description": "Supervises the field technician team and schedules work.",
      "memberCount": 2,
      "parentRoleId": "1c0f8b2a-7d34-4e91-bf02-3a5d9c6e8f10",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-05-20T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Field	Type	Notes
description	string | null	The role’s description, if set.
memberCount	number	How many people currently hold the role.
parentRoleId	string | null	The role this one reports to; null at the top of the chart.

Get a company role

GET /v1/company-roles/{id}

Role detail: the summary fields plus the role’s training curriculum (the lessons and topics everyone in the role must complete) and its current members. Returns 404 if the role is not visible to you.

Response

{
  "id": "695690de-1c49-42c7-a416-b0d3bea29102",
  "name": "Service Manager",
  "description": "Supervises the field technician team and schedules work.",
  "memberCount": 2,
  "parentRoleId": "1c0f8b2a-7d34-4e91-bf02-3a5d9c6e8f10",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "updatedAt": "2026-05-20T10:00:00.000Z",
  "curriculum": [
    { "type": "lesson", "id": "lsn_6e3f...", "name": "Scheduling and dispatch" },
    { "type": "topic", "id": "t_91ab...", "name": "Maintenance plans" }
  ],
  "members": [
    { "id": "usr_44de...", "name": "Carla Field" }
  ]
}

Field	Type	Notes
curriculum[].type	string	lesson or topic.
curriculum[].id	string	The lesson or topic id. Resolve a lesson with /v1/lessons/{id}, a topic with /v1/topics/{id}.
members[]	object	Each holder’s id and name.

List a role’s duties

GET /v1/company-roles/{id}/duties

Everything this role answers for, from the holder’s side. The duties endpoint answers the opposite question: who answers for a given topic.

Query parameters

Parameter	Type	Notes
entityType	string	TOPIC, ITEM, SPACE, or CATEGORY. Worth using: a duty on a topic reaches every item on it, so an unfiltered list is mostly items.
cursor	string	Pagination cursor from a previous response.
limit	number	1–100. Default 50.

Request

curl "https://api.mereon.ai/v1/company-roles/695690de/duties?entityType=TOPIC" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "role": "ACCOUNTABLE",
      "entityType": "TOPIC",
      "entityId": "top_9f2a...",
      "entityName": "Expense approval",
      "inheritedFrom": { "entityType": "SPACE", "entityId": "spc_4c81..." },
      "tierQualifier": "MIN_TIER",
      "advancementTierId": "tier_7a12...",
      "advancementTierLabel": "Senior",
      "url": "https://mereon.ai/topics/expense-approval"
    }
  ],
  "nextCursor": null
}

Field	Type	Notes
role	string	RESPONSIBLE, ACCOUNTABLE, CONSULTED, or INFORMED.
entityName	string	Resolved so the row stands alone. Duties on entities no longer in the live graph are omitted, so this is always present.
inheritedFrom	object | null	The ancestor the duty reaches this entity through, or null when assigned directly. A duty on a space is reported against each topic in it.
tierQualifier	string	How far the duty reaches across the role’s advancement path: ALL, MIN_TIER, MAX_TIER, or EXACT_TIER. ALL when the role has no path.
advancementTierLabel	string | null	The tier the qualifier refers to, when one applies.

Caution

This lists duties assigned to the role. It does not include company-wide policies the role’s holders also carry — a duty given to everyone in the organization, or to every internal or external role, is held by the organization rather than by any one role, so it will not appear here even though the people in this role answer for it.

Rows are ordered by entity type then name, and the list is limited to entities the caller can read. A duty held at the space or category level expands to one row per descendant, so it can be long — which is what entityType is for.