Duties

Duties answer “who owns this”. Mereon tracks ownership using the RACI model: who is Responsible, Accountable, Consulted, or Informed for a topic, item, space, or category. Duties can be assigned directly or inherited from a parent area. Reading them needs the raci-assignment.read permission, which every role has except external; an external account gets 403, as it does in the app. Assigning, changing, or removing one needs duty:manage. Owners and admins can do that. A duty assigned here is recorded as set by a person. Copying duties down to child topics, and handing one role’s duties to another role, stay in the app.

Get duties for an entity

GET /v1/duties

Returns the effective duties for one entity, including inherited ones.

Query parameters

Parameter	Type	Notes
entityType	string	One of TOPIC, ITEM, SPACE, CATEGORY. Required.
entityId	string	The entity’s id. Required.

Request

curl "https://api.mereon.ai/v1/duties?entityType=TOPIC&entityId=top_9f2a" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "role": "ACCOUNTABLE",
      "actorType": "INDIVIDUAL",
      "actorId": "emp_7c41...",
      "actorUserId": "usr_8s2k...",
      "actorDisplayName": "Alex Doe",
      "inheritedFrom": null,
      "assignmentId": "ras_71b3...",
      "source": "MANUAL",
      "confidence": null,
      "learningPriorityOverride": null
    },
    {
      "role": "CONSULTED",
      "actorType": "ROLE",
      "actorId": "rol_1122...",
      "actorUserId": null,
      "actorDisplayName": "Finance Manager",
      "inheritedFrom": { "entityType": "CATEGORY", "entityId": "cat_finance" },
      "assignmentId": "ras_0d92...",
      "source": "AI_ENHANCED",
      "confidence": 0.82,
      "learningPriorityOverride": "HIGH"
    }
  ]
}

Fields

Field	Type	Notes
role	string	RESPONSIBLE, ACCOUNTABLE, CONSULTED, or INFORMED.
actorType	string	What kind of actor holds the duty: INDIVIDUAL, TEAM, ROLE, THIRD_PARTY, ORGANIZATION, or ROLE_KIND.
actorId	string	The actor’s id. For INDIVIDUAL this identifies the organization’s record of the person, not their login. The same person has a different record in each organization they belong to.
actorUserId	string | null	The login behind an INDIVIDUAL actor, which is the id you will find on user-keyed resources. null for every other actor type, and for a person the organization records without an account.
actorDisplayName	string	Human-readable name of the actor.
inheritedFrom	object | null	The parent entity the duty was inherited from, or null if assigned directly.
assignmentId	string	The assignment behind this duty. For an inherited duty it is the parent’s assignment, not one on the entity you asked about.
source	string	Who set the duty: MANUAL for a person’s own assignment, or AI_ENHANCED or AI_CLASSIFIED for the system’s suggestion. Most owners are suggestions, so this is what separates a confirmed owner from a proposed one.
confidence	number | null	How sure the suggestion was, from 0 to 1. null for a person’s own assignment.
learningPriorityOverride	string | null	This duty’s own learning priority (CRITICAL, HIGH, MEDIUM, or LOW). null means the topic’s priority applies.

Note

Before September 2026, an INDIVIDUAL duty’s actorId was the person’s login id. It now identifies the organization’s record of that person, and actorUserId carries the login. If your integration matched actorId against user ids, read actorUserId instead.

Tip

An empty data array means no one is assigned for that entity, directly or by inheritance. That itself can be a useful signal for a knowledge-ownership audit.

Assign a duty

POST /v1/duties

Assigns who is Responsible, Accountable, Consulted, or Informed for a topic, item, space, or category. The duty is recorded as set by a person. For a person, actorId may be the organization’s record of them, which is what a duty read returns, or their login id, which is what the member list returns. Leave actorId out for an organization-wide duty, which covers the organization this token belongs to. For ROLE_KIND, actorId is INTERNAL or EXTERNAL. A company role may set tierQualifier and advancementTierId so the duty covers part of its advancement path. Other actor types may not. Accountable cannot name everyone. An entity you cannot read, or one outside the organization, is refused with 404. Limited to 10 calls a minute and 60 an hour.

Request body

Field	Type	Required	Notes
actorType	string	yes	ROLE, TEAM, INDIVIDUAL, THIRD_PARTY, ORGANIZATION, or ROLE_KIND.
actorId	string	no	Who holds the duty. Required except for ORGANIZATION. INTERNAL or EXTERNAL for ROLE_KIND.
entityType	string	yes	TOPIC, ITEM, SPACE, or CATEGORY.
entityId	string	yes	The topic, item, space, or category.
role	string	yes	RESPONSIBLE, ACCOUNTABLE, CONSULTED, or INFORMED.
tierQualifier	string	no	ALL, MIN, MAX, or EXACT. Only a company role may set this. Defaults to ALL.
advancementTierId	string | null	no	The tier a MIN, MAX, or EXACT duty is bound to. Omit it for ALL.

Request

curl -X POST "https://api.mereon.ai/v1/duties" \
  -H "Authorization: Bearer $MEREON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "actorType": "ROLE", "actorId": "rol_1122", "entityType": "TOPIC", "entityId": "top_9f2a", "role": "ACCOUNTABLE" }'

Response

201 Created. The duty that was written. This is the assignment itself, not the effective list above, so it has no inheritedFrom.

Field	Type	Notes
id	string	The duty id a later change or removal names. A read calls this assignmentId.
actorType	string	The same kinds as the request.
actorId	string	For a person, the organization’s record of them, including when the request named their login.
actorDisplayName	string	Human-readable name of the actor.
actorUserId	string | null	The login behind a person. null for every other actor type.
role	string	RESPONSIBLE, ACCOUNTABLE, CONSULTED, or INFORMED.
entityType	string	TOPIC, ITEM, SPACE, or CATEGORY.
entityId	string	The entity the duty sits on.
tierQualifier	string	ALL, MIN, MAX, or EXACT.
advancementTierId	string | null	The tier a narrowed company-role duty is bound to.
advancementTierLabel	string | null	That tier’s label.
source	string	MANUAL. A duty assigned here is a person’s own assignment.
confidence	number | null	null for a person’s own assignment.
learningPriorityOverride	string | null	CRITICAL, HIGH, MEDIUM, or LOW. null means the topic’s priority applies.
createdAt	string	ISO 8601.
updatedAt	string	ISO 8601.

Change a duty

PATCH /v1/duties/{id}

Changes the level, the learning priority, or how far a company role’s duty reaches on its advancement path. Send at least one of role, learningPriorityOverride, tierQualifier, and advancementTierId. The actor and the entity stay as they are. learningPriorityOverride null clears it so the topic’s priority applies. A duty in another organization, or on an entity you cannot read, is refused with 404. The same limit as assigning a duty.

Request body

Field	Type	Required	Notes
role	string	no	RESPONSIBLE, ACCOUNTABLE, CONSULTED, or INFORMED.
learningPriorityOverride	string | null	no	CRITICAL, HIGH, MEDIUM, or LOW. null clears it.
tierQualifier	string	no	ALL, MIN, MAX, or EXACT. Only a duty held by a company role may set this.
advancementTierId	string | null	no	The tier a MIN, MAX, or EXACT duty is bound to. Omit it for ALL.

Response

200 OK. The duty, in the same shape as assigning one.

Remove a duty

DELETE /v1/duties/{id}

Removes a duty. A duty in another organization, or on an entity you cannot read, is refused with 404. The same limit as assigning a duty.

Response

200 OK. The duty that was removed, in the same shape as assigning one.

Errors

Status	When
400	The body is not the schema’s, the actor is not in this organization, an organization-wide duty names a different organization, Accountable names everyone, a tier qualifier is used on an actor that is not a company role, or this actor already holds that level on this entity.
403	The token lacks duty:manage, or the caller may not take that action.
404	The entity or the duty is not in this organization, or you cannot read the entity it sits on.
429	More than 10 calls a minute, or 60 an hour, on that route. Retry-After says when to try again.