Org Unit API

Table of Contents

• upsquad/orgunit/v1/orgunit.proto

  • AcceptOfferRequest

  • AcceptOfferResponse

  • AcceptedOffer

  • AddUnitRelationRequest

  • AddUnitRelationResponse

  • AdminResolveAllTeamsUnionRequest

  • AdminResolveAllTeamsUnionResponse

  • AppointUnitAdminRequest

  • AppointUnitAdminResponse

  • ApproveModelAllowlistEntryRequest

  • ApproveModelAllowlistEntryResponse

  • ApproveUnitAdminRequest

  • ApproveUnitAdminResponse

  • AssignMemberRequest

  • AssignMemberResponse

  • AttachToolRequest

  • AttachToolResponse

  • ConflictResolution

  • CreateUnitRequest

  • CreateUnitResponse

  • DeclineOfferRequest

  • DeclineOfferResponse

  • DeleteUnitRequest

  • DeleteUnitResponse

  • DenyModelAllowlistEntryRequest

  • DenyModelAllowlistEntryResponse

  • DetachToolRequest

  • DetachToolResponse

  • EffectiveConfig

  • EffectiveGuardrail

  • EffectiveItem

  • EffectiveToolBinding

  • GetTeamModelAllowlistRequest

  • GetTeamModelAllowlistResponse

  • GetTreeRequest

  • GetTreeResponse

  • GetUnitManagerRequest

  • GetUnitManagerResponse

  • GetUnitRequest

  • GetUnitResponse

  • ListMembershipsForMemberRequest

  • ListMembershipsForMemberResponse

  • ListMembershipsForUnitRequest

  • ListMembershipsForUnitResponse

  • ListOffersRequest

  • ListOffersResponse

  • ListPendingModelAllowlistEntriesRequest

  • ListPendingModelAllowlistEntriesResponse

  • ListTeamModelsRequest

  • ListTeamModelsResponse

  • ListToolsForMemberRequest

  • ListToolsForMemberResponse

  • ListToolsForUnitRequest

  • ListToolsForUnitResponse

  • ListUnitAdminsRequest

  • ListUnitAdminsResponse

  • ListUnitRelationsRequest

  • ListUnitRelationsResponse

  • ListUnitsRequest

  • ListUnitsResponse

  • MarkShareableRequest

  • MarkShareableResponse

  • Membership

  • MergeUnitsRequest

  • MergeUnitsResponse

  • ModelAllowlistEntry

  • MoveUnitRequest

  • MoveUnitResponse

  • Offer

  • Provenance

  • PublishGovernedUnitOpRequest

  • PublishGovernedUnitOpResponse

  • RejectUnitAdminRequest

  • RejectUnitAdminResponse

  • RemoveMemberRequest

  • RemoveMemberResponse

  • RemoveUnitAdminRequest

  • RemoveUnitAdminResponse

  • RemoveUnitRelationRequest

  • RemoveUnitRelationResponse

  • RequestToolOverrideRequest

  • RequestToolOverrideResponse

  • ResolveEffectiveConfigForMemberRequest

  • ResolveEffectiveConfigForMemberResponse

  • ResolveEffectiveConfigRequest

  • ResolveEffectiveConfigResponse

  • ResolveToolOverrideRequest

  • ResolveToolOverrideResponse

  • RouteTeamRequest

  • RouteTeamResponse

  • SetHomeParentRequest

  • SetHomeParentResponse

  • SetTeamModelAllowlistRequest

  • SetTeamModelAllowlistResponse

  • SetUnitManagerRequest

  • SetUnitManagerResponse

  • SplitUnitRequest

  • SplitUnitResponse

  • TeamModel

  • ToolBinding

  • ToolConfigConflict

  • TreeNode

  • Unit

  • UnitAdmin

  • UnitRelation

  • UpdateUnitRequest

  • UpdateUnitResponse

  • AdminAppointmentState

  • ConflictPolicy

  • GovernedOpStatus

  • OfferKind

  • ProvenanceVia

  • OrgUnitService

• Scalar Value Types

Top

upsquad/orgunit/v1/orgunit.proto

AcceptOfferRequest

Field	Type	Label	Description
accepting_unit_id	string
kind	OfferKind
item_id	string
from_unit_id	string

AcceptOfferResponse

Field	Type	Label	Description
accepted_offer	AcceptedOffer

AcceptedOffer

AcceptedOffer is the wire form of a unit_accepted_offers row.

Field	Type	Label	Description
id	string
org_id	string
accepting_unit_id	string
kind	OfferKind
item_id	string
from_unit_id	string
accepted_by	string
accepted_at	google.protobuf.Timestamp

AddUnitRelationRequest

Field	Type	Label	Description
parent_unit_id	string
child_unit_id	string
label	string

AddUnitRelationResponse

Field	Type	Label	Description
status	GovernedOpStatus
draft_id	string		draft_id is the org_draft that carries the pending/published op.
approval_id	string		approval_id is the resource-scoped approval opened for a PENDING op.
relation	UnitRelation		relation is populated when status == APPLIED.

AdminResolveAllTeamsUnionRequest

AdminResolveAllTeamsUnionRequest is the FR-15 admin/audit union request.

Field	Type	Label	Description
org_id	string
member_id	string

AdminResolveAllTeamsUnionResponse

Field	Type	Label	Description
config	EffectiveConfig

AppointUnitAdminRequest

Field	Type	Label	Description
unit_id	string
candidate_member_id	string

AppointUnitAdminResponse

Field	Type	Label	Description
status	GovernedOpStatus
draft_id	string
approval_id	string
missing_privileges	string	repeated	missing_privileges lists the capability floors the candidate fails (populated when status == REJECTED per FR-30).

ApproveModelAllowlistEntryRequest

ApproveModelAllowlistEntryRequest approves a single pending entry.

Field	Type	Label	Description
entry_id	string		entry_id is the pending ModelAllowlistEntry to approve. Required.
decided_by	string		decided_by is the acting Manager's member id — carried explicitly per the orgunit service convention (matches SetTeamModelAllowlist.configured_by).

ApproveModelAllowlistEntryResponse

ApproveModelAllowlistEntryResponse carries the post-approval entry.

Field	Type	Label	Description
entry	ModelAllowlistEntry		entry is the entry after transition (approval_status='approved').

ApproveUnitAdminRequest

Field	Type	Label	Description
draft_id	string

ApproveUnitAdminResponse

Field	Type	Label	Description
status	GovernedOpStatus

AssignMemberRequest

Field	Type	Label	Description
org_id	string		org_id is the tenant organisation UUID.
member_id	string		member_id is the UUID of the member.
unit_id	string		unit_id is the UUID of the unit.
role	string		role is one of member

AssignMemberResponse

Field	Type	Label	Description
membership	Membership		membership is the created or updated membership.
already_existed	bool		already_existed is true when the (member, unit) pair was already present.

AttachToolRequest

Field	Type	Label	Description
unit_id	string
tool_id	string
config_json	string
visibility	string
configured_by	string

AttachToolResponse

Field	Type	Label	Description
binding	ToolBinding

ConflictResolution

ConflictResolution records one name collision and the action taken.

Field	Type	Label	Description
child_name	string		child_name is the colliding display name.
policy	ConflictPolicy		policy is the policy applied to this conflict (echoes the request policy for now; future per-row policy hooks would diverge here).
moved_unit_id	string		moved_unit_id is the UUID of the source-side child involved in the collision.
target_unit_id	string		target_unit_id is the UUID of the target-side child that already owned child_name.
resulting_name	string		resulting_name is the post-resolution name carried by moved_unit_id when the policy was RENAME (e.g. "Engineering (merged)"). Empty when the policy was SKIP or OVERWRITE.

CreateUnitRequest

Field	Type	Label	Description
org_id	string		org_id is the tenant organisation UUID.
parent_id	string		parent_id is the UUID of the parent unit; empty = root.
name	string		name is the display name of the unit.
unit_type	string		unit_type is "pillar"

CreateUnitResponse

Field	Type	Label	Description
unit	Unit		unit is the newly created unit (with ancestor_path and depth).

DeclineOfferRequest

Field	Type	Label	Description
accepting_unit_id	string
kind	OfferKind
item_id	string
from_unit_id	string

DeclineOfferResponse

Field	Type	Label	Description
declined	bool

DeleteUnitRequest

Field	Type	Label	Description
id	string		id is the unit UUID.
reparent_children	bool		reparent_children, when true, moves the unit's direct children up to the deleted unit's parent before the soft-delete.

DeleteUnitResponse

Field	Type	Label	Description
deleted_at	google.protobuf.Timestamp		deleted_at is the soft-delete timestamp.
reparented_count	int32		reparented_count is the number of direct children that were moved.

DenyModelAllowlistEntryRequest

DenyModelAllowlistEntryRequest denies a single pending entry.

Field	Type	Label	Description
entry_id	string		entry_id is the pending ModelAllowlistEntry to deny. Required.
decided_by	string		decided_by is the acting Manager's member id.
reason	string		reason is the optional free-text denial reason.

DenyModelAllowlistEntryResponse

DenyModelAllowlistEntryResponse carries the post-denial entry.

Field	Type	Label	Description
entry	ModelAllowlistEntry		entry is the entry after transition (approval_status='denied').

DetachToolRequest

Field	Type	Label	Description
unit_id	string
tool_id	string

DetachToolResponse

Field	Type	Label	Description
detached	bool

EffectiveConfig

EffectiveConfig is the per-axis resolved config for a (member/unit) context.

Field	Type	Label	Description
guardrails	EffectiveGuardrail	repeated	guardrails are PUSH-inherited across home ∪ relation edges (mandatory).
tools	EffectiveItem	repeated	tools are home inherit_down ∪ accepted cross offers.
mcp	EffectiveItem	repeated	mcp are home inherit ∪ accepted cross offers.
knowledge	EffectiveItem	repeated	knowledge are home inherit ∪ accepted cross offers.

EffectiveGuardrail

EffectiveGuardrail is a resolved guardrail rule with its severity + action.

Field	Type	Label	Description
item_id	string		item_id is the canonical rule id "action_type
action_type	string		action_type is the guarded action (parsed from item_id).
target	string		target is the guarded target (parsed from item_id).
severity	string		severity is the most-restrictive band across all sources ("low"
sources	Provenance	repeated	sources are the contributing units (union, all retained).

EffectiveItem

EffectiveItem is a resolved tool / MCP / knowledge item with provenance.

Field	Type	Label	Description
item_id	string		item_id is the axis-specific opaque id (tool_id
sources	Provenance	repeated	sources are the contributing units (union, all retained).

EffectiveToolBinding

Field	Type	Label	Description
binding	ToolBinding
effective_source	string
source_unit_id	string

GetTeamModelAllowlistRequest

Field	Type	Label	Description
unit_id	string		unit_id is the org_unit (team) id.

GetTeamModelAllowlistResponse

Field	Type	Label	Description
entries	ModelAllowlistEntry	repeated	entries is the current allowlist; empty = allow all.

GetTreeRequest

Field	Type	Label	Description
org_id	string		org_id is the tenant organisation UUID.
root_id	string		root_id optionally roots the tree at a specific unit; empty = all roots.
max_depth	int32		max_depth limits the depth relative to the root; 0 = unlimited.

GetTreeResponse

Field	Type	Label	Description
nodes	TreeNode	repeated	nodes is the flat list ordered root→children depth-first.
total_units	int32		total_units is the count of nodes returned.

GetUnitManagerRequest

Field	Type	Label	Description
unit_id	string

GetUnitManagerResponse

Field	Type	Label	Description
manager_member_id	string		manager_member_id is empty when the unit has no assigned Manager.

GetUnitRequest

Field	Type	Label	Description
id	string		id is the unit UUID.

GetUnitResponse

Field	Type	Label	Description
unit	Unit		unit is the requested unit (includes direct_child_count).

ListMembershipsForMemberRequest

Field	Type	Label	Description
member_id	string		member_id is the UUID of the member.

ListMembershipsForMemberResponse

Field	Type	Label	Description
memberships	Membership	repeated	memberships is the full list (no pagination — typical members belong to <20 units).

ListMembershipsForUnitRequest

Field	Type	Label	Description
unit_id	string		unit_id is the UUID of the unit.
page_size	int32		page_size is the maximum number of results per page; default 50, max 100.
page_token	int32		page_token is the 0-based offset.

ListMembershipsForUnitResponse

Field	Type	Label	Description
memberships	Membership	repeated	memberships is the page of memberships for the unit.
total_count	int32		total_count is the total matching memberships.

ListOffersRequest

Field	Type	Label	Description
unit_id	string
kind	OfferKind

ListOffersResponse

Field	Type	Label	Description
offers	Offer	repeated

ListPendingModelAllowlistEntriesRequest

ListPendingModelAllowlistEntriesRequest scopes the inbox to a Manager.

Field	Type	Label	Description
manager_member_id	string		manager_member_id selects the pending entries of the teams this member manages (org_units.manager_member_id). Required.

ListPendingModelAllowlistEntriesResponse

ListPendingModelAllowlistEntriesResponse returns the Manager's pending model-approval queue.

Field	Type	Label	Description
entries	ModelAllowlistEntry	repeated	entries are the pending entries awaiting this Manager's decision, oldest-first.

ListTeamModelsRequest

ListTeamModelsRequest asks for a team's selectable model set.

Field	Type	Label	Description
unit_id	string		unit_id is the org_unit (team) id whose effective model set is resolved. Required.

ListTeamModelsResponse

ListTeamModelsResponse carries the effective, catalogue-enriched model set.

Field	Type	Label	Description
models	TeamModel	repeated	models is the selectable set: the team's approved allowlist enriched from the catalogue, OR — when the approved set is empty — the full tenant provider-backed catalogue. Deterministically ordered (provider, then model_id) so the picker is stable.
restricted	bool		restricted is true when the team has a non-empty approved allowlist (the returned set IS the allowlist). False when the allowlist is empty and the full catalogue was returned as the fallback.

ListToolsForMemberRequest

Field	Type	Label	Description
member_id	string

ListToolsForMemberResponse

Field	Type	Label	Description
bindings	EffectiveToolBinding	repeated

ListToolsForUnitRequest

Field	Type	Label	Description
unit_id	string

ListToolsForUnitResponse

Field	Type	Label	Description
bindings	ToolBinding	repeated

ListUnitAdminsRequest

Field	Type	Label	Description
unit_id	string

ListUnitAdminsResponse

Field	Type	Label	Description
manager_member_id	string
admins	UnitAdmin	repeated

ListUnitRelationsRequest

Field	Type	Label	Description
unit_id	string

ListUnitRelationsResponse

Field	Type	Label	Description
parents	UnitRelation	repeated	parents are edges where unit_id is the child (its additional parents).
children	UnitRelation	repeated	children are edges where unit_id is the parent.

ListUnitsRequest

Field	Type	Label	Description
org_id	string		org_id is the tenant organisation UUID.
parent_id_filter	string		parent_id_filter restricts results to children of this parent; empty = no filter.
unit_type_filter	string		unit_type_filter restricts results to a unit_type; empty = all types.
page_size	int32		page_size is the maximum number of results per page; default 50, max 100.
page_token	int32		page_token is the 0-based offset.

ListUnitsResponse

Field	Type	Label	Description
units	Unit	repeated	units is the page of units.
total_count	int32		total_count is the total matching units.

MarkShareableRequest

Field	Type	Label	Description
unit_id	string
kind	OfferKind
item_id	string		item_id is the tool_id
shareable	bool

MarkShareableResponse

Field	Type	Label	Description
shareable	bool

Membership

Membership is the wire form of an org_unit_memberships row.

Field	Type	Label	Description
id	string		id is the stable UUID of the membership row.
org_id	string		org_id is the tenant organisation UUID.
member_id	string		member_id is the UUID of the member.
unit_id	string		unit_id is the UUID of the unit.
unit_name	string		unit_name is a denormalised helper populated by ListMembershipsForMember.
role	string		role is one of member
created_at	google.protobuf.Timestamp		created_at is the membership creation timestamp.

MergeUnitsRequest

MergeUnitsRequest folds source_id into target_id.

Field	Type	Label	Description
source_id	string		source_id is the UUID of the unit being absorbed. Soft-deleted at end of merge.
target_id	string		target_id is the UUID of the unit receiving source's children + memberships.
conflict_policy	ConflictPolicy		conflict_policy decides how name collisions on direct children of source vs target are resolved. UNSPECIFIED = RENAME.

MergeUnitsResponse

MergeUnitsResponse describes the post-merge state of target plus a per-conflict ledger so the UI can surface which children were renamed / skipped / overwritten.

Field	Type	Label	Description
merged_unit	Unit		merged_unit is the post-merge state of target_id (children + memberships are now its own).
source_deleted_at	google.protobuf.Timestamp		source_deleted_at is the soft-delete timestamp on source_id.
children_moved	int32		children_moved is the count of source's direct children that were reparented to target (not including those skipped or overwritten).
memberships_moved	int32		memberships_moved is the count of org_unit_memberships rows whose unit_id was rewritten from source to target.
conflicts_resolved	ConflictResolution	repeated	conflicts_resolved is the per-name-collision audit ledger.

ModelAllowlistEntry

ModelAllowlistEntry records that a model_id is permitted for the team.

Field	Type	Label	Description
unit_id	string		unit_id is the org_unit (team) id.
model_id	string		model_id is the canonical model identifier from the ModelRegistry catalogue (e.g. "claude-sonnet-4-20250514").
created_at	google.protobuf.Timestamp		created_at is the row creation timestamp.
entry_id	string		entry_id is the row id — the target of ApproveModelAllowlistEntry / DenyModelAllowlistEntry. Added by #1705.
approval_status	string		approval_status is the per-team model approval gate (T6/#1689 + #1705): pending
configured_by	string		configured_by is the member who proposed the entry (audit actor).
decided_by	string		decided_by is the Manager who approved/denied it; empty until decided.
decided_at	google.protobuf.Timestamp		decided_at is the decision timestamp; unset until decided.
decision_reason	string		decision_reason is the optional free-text reason (esp. for a denial).

MoveUnitRequest

Field	Type	Label	Description
id	string		id is the unit UUID to reparent.
new_parent_id	string		new_parent_id is the new parent UUID; empty = make root.

MoveUnitResponse

Field	Type	Label	Description
unit	Unit		unit is the moved unit with recomputed ancestor_path and depth.
cascaded_count	int32		cascaded_count is the number of descendants whose paths were recomputed.

Offer

Offer is a shareable item offered by another unit.

Field	Type	Label	Description
from_unit_id	string
kind	OfferKind
item_id	string
accepted	bool		accepted is true when unit_id already holds an accepted-offer row for it.

Provenance

Provenance names one contributing unit for a resolved item (FR-23 explain view). Every effective item carries one Provenance per contributing source.

Field	Type	Label	Description
source_unit_id	string		source_unit_id is the org_unit the item is attached to (its origin).
source_unit_name	string		source_unit_name is the display name of source_unit_id (enrichment).
via	ProvenanceVia		via is the edge the item travelled (HOME chain vs cross RELATION).
path	string	repeated	path is the unit-id chain from the source unit down to the active team, for rendering the inheritance route in the explain view.
accepted_from_unit_id	string		accepted_from_unit_id is set ONLY for an accepted cross-cutting offer: the HOME unit that opted in via unit_accepted_offers (two-sided OFFER→ACCEPT). Empty for home-chain items and mandatory guardrail pushes.

PublishGovernedUnitOpRequest

Field	Type	Label	Description
draft_id	string

PublishGovernedUnitOpResponse

Field	Type	Label	Description
status	GovernedOpStatus
op_type	string		op_type is the applied op (relate
approval_id	string

RejectUnitAdminRequest

Field	Type	Label	Description
draft_id	string
reason	string

RejectUnitAdminResponse

Field	Type	Label	Description
rejected	bool

RemoveMemberRequest

Field	Type	Label	Description
member_id	string		member_id is the UUID of the member.
unit_id	string		unit_id is the UUID of the unit.

RemoveMemberResponse

Field	Type	Label	Description
removed	bool		removed is true when a row was actually deleted.

RemoveUnitAdminRequest

Field	Type	Label	Description
unit_id	string
member_id	string

RemoveUnitAdminResponse

Field	Type	Label	Description
removed	bool

RemoveUnitRelationRequest

Field	Type	Label	Description
parent_unit_id	string
child_unit_id	string

RemoveUnitRelationResponse

Field	Type	Label	Description
status	GovernedOpStatus
draft_id	string
approval_id	string
removed	bool		removed is true when status == APPLIED and an edge was soft-deleted.

RequestToolOverrideRequest

Field	Type	Label	Description
parent_unit_id	string
child_unit_id	string
tool_id	string
child_config_json	string
justification	string
requested_by	string

RequestToolOverrideResponse

Field	Type	Label	Description
conflict	ToolConfigConflict

ResolveEffectiveConfigForMemberRequest

Field	Type	Label	Description
org_id	string
member_id	string
active_unit_id	string		active_unit_id is the team context to resolve in. For an agent this is its single home team.

ResolveEffectiveConfigForMemberResponse

Field	Type	Label	Description
config	EffectiveConfig
multi_parent_active	bool

ResolveEffectiveConfigRequest

Field	Type	Label	Description
org_id	string
unit_id	string		unit_id is the team whose effective config to resolve (treated as the active team).

ResolveEffectiveConfigResponse

Field	Type	Label	Description
config	EffectiveConfig
multi_parent_active	bool		multi_parent_active reflects the orgv24.multiparent_resolver read-switch state that produced this result (false ⇒ v2.3-equivalent home-only output).

ResolveToolOverrideRequest

Field	Type	Label	Description
conflict_id	string
approve	bool
note	string
resolved_by	string

ResolveToolOverrideResponse

Field	Type	Label	Description
conflict	ToolConfigConflict
binding	ToolBinding

RouteTeamRequest

Field	Type	Label	Description
org_id	string		org_id is the tenant organisation UUID.
intent_tags	string	repeated	intent_tags are the Task's classified intent tags (e.g. ["billing", "refund"]). Matched case-insensitively against team domain/capabilities.

RouteTeamResponse

Field	Type	Label	Description
team_id	string		team_id is the org_unit id of the matched team.

SetHomeParentRequest

Field	Type	Label	Description
unit_id	string
new_parent_id	string		new_parent_id is the target HOME parent; empty promotes the unit to a root.

SetHomeParentResponse

Field	Type	Label	Description
unit	Unit

SetTeamModelAllowlistRequest

Field	Type	Label	Description
unit_id	string		unit_id is the org_unit (team) id.
model_ids	string	repeated	model_ids is the full replacement set. Empty = no restriction.
configured_by	string		configured_by is the caller's member id, carried explicitly per the orgunit service convention (matches AttachTool's configured_by field).

SetTeamModelAllowlistResponse

Field	Type	Label	Description
entries	ModelAllowlistEntry	repeated	entries is the persisted list after replacement.

SetUnitManagerRequest

Field	Type	Label	Description
unit_id	string
new_manager_member_id	string

SetUnitManagerResponse

Field	Type	Label	Description
status	GovernedOpStatus
draft_id	string
approval_id	string
manager_member_id	string		manager_member_id echoes the applied Manager when status == APPLIED.

SplitUnitRequest

SplitUnitRequest creates a new sibling unit under source's parent and moves the requested members across.

Field	Type	Label	Description
source_id	string		source_id is the UUID of the existing unit being split.
new_unit_name	string		new_unit_name is the display name for the freshly created sibling.
member_ids	string	repeated	member_ids is the list of member UUIDs to move from source to the new unit. Must contain at least one id. Members not currently in source are silently ignored (idempotent).

SplitUnitResponse

SplitUnitResponse returns both units after the split commits.

Field	Type	Label	Description
original	Unit		original is the post-split state of source (members moved out).
new_unit	Unit		new_unit is the freshly created sibling of source (members moved in).
memberships_moved	int32		memberships_moved is the count of org_unit_memberships rows whose unit_id was rewritten from source to new_unit.

TeamModel

TeamModel is one EFFECTIVE, selectable model for a team (#2008). Unlike ModelAllowlistEntry (which mirrors a raw allowlist row and includes the approval axis) this is the resolved, catalogue-enriched view the model picker renders: only approved / provider-backed models, each with the provider + display_name the catalogue carries.

Field	Type	Label	Description
model_id	string		model_id is the canonical model identifier (e.g. "claude-sonnet-4-20250514").
provider	string		provider is the LLM provider ("anthropic", "openai", "google", "ollama"). Sourced from the platform seed catalogue; empty when the id is in the team's approved allowlist but absent from the catalogue (see is_known).
display_name	string		display_name is the human-readable model name for UI display. Falls back to model_id when the id is not in the catalogue.
is_default	bool		is_default is true for the entry that matches the agent-configuration default model (claude-sonnet-4-20250514) — the value the picker preselects.
is_known	bool		is_known is false when the model_id came from the team's approved allowlist but is NOT in the current platform catalogue (a stale/removed model). The UI renders these with an "unknown model" marker. Always true for the empty-allowlist fallback (every entry is a live catalogue model).

ToolBinding

ToolBinding is the wire form of an org_unit_tools row.

Field	Type	Label	Description
id	string
org_id	string
unit_id	string
tool_id	string
config_json	string
visibility	string
configured_by	string
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

ToolConfigConflict

Field	Type	Label	Description
id	string
org_id	string
tool_id	string
parent_unit_id	string
child_unit_id	string
parent_config_json	string
child_config_json	string
justification	string
status	string
requested_by	string
resolution_override_granted_by	string
resolution_note	string
created_at	google.protobuf.Timestamp
resolved_at	google.protobuf.Timestamp

TreeNode

TreeNode is the flat-list form used by GetTree. Callers reconstruct a nested tree from (id, parent_id, depth).

Field	Type	Label	Description
id	string		id is the UUID of the unit.
parent_id	string		parent_id is empty for roots.
name	string		name is the display name.
unit_type	string		unit_type is "pillar"
depth	int32		depth is the tree depth (0 for roots).
direct_child_count	int32		direct_child_count is the number of immediate children.

Unit

Unit is the wire form of an org_units row.

Field	Type	Label	Description
id	string		id is the stable UUID of the unit.
org_id	string		org_id is the tenant organisation UUID.
parent_id	string		parent_id is the UUID of the parent unit; empty for roots.
name	string		name is the display name of the unit.
unit_type	string		unit_type is one of "pillar"
ancestor_path	string	repeated	ancestor_path is the materialised chain of ancestor UUIDs ordered root→parent (NOT including this unit's own id).
depth	int32		depth is len(ancestor_path). 0 for roots.
direct_child_count	int32		direct_child_count is the count of non-deleted immediate children (populated by GetUnit and tree queries only; zero elsewhere).
created_at	google.protobuf.Timestamp		created_at is the row creation timestamp.
updated_at	google.protobuf.Timestamp		updated_at is the last update timestamp (mutated by triggers + service writes).
deleted_at	google.protobuf.Timestamp		deleted_at is set when the unit is soft-deleted; null for active units.
domain	string		domain is the routing domain a team unit handles (e.g. "billing", "support"). Empty for units that opt out of metadata routing. MVP work-routing (#1234, ADR-0015): the deterministic matcher prefers a team whose domain equals one of a Task's intent tags. Meaningful only for unit_type=team; empty on pillars.
capabilities	string	repeated	capabilities are free-form capability tags a team unit can service (e.g. ["refund", "invoice"]). The matcher scores capability overlap with a Task's intent tags below a domain match. Order is not significant.

UnitAdmin

UnitAdmin is one admin entry (active membership or pending appointment).

Field	Type	Label	Description
unit_id	string
member_id	string
state	AdminAppointmentState
draft_id	string		draft_id / approval_id are populated for PENDING appointments.
approval_id	string
appointed_at	google.protobuf.Timestamp

UnitRelation

UnitRelation is the wire form of a unit_relations edge (additional parent).

Field	Type	Label	Description
id	string
org_id	string
parent_unit_id	string
child_unit_id	string
label	string		label is free-text display only, ZERO behaviour (FR-5).
created_by	string
created_at	google.protobuf.Timestamp

UpdateUnitRequest

Field	Type	Label	Description
id	string		id is the unit UUID.
name	string		name is the new name; empty = no change.
unit_type	string		unit_type is the new unit_type; empty = no change.
domain	string		domain sets the team-routing domain; empty = no change (#1234).
capabilities	string	repeated	capabilities replaces the unit's capability tag set when update_capabilities is true; ignored otherwise (#1234).
update_capabilities	bool		update_capabilities, when true, replaces capabilities with the supplied list (an empty list clears them). When false, capabilities are left unchanged so a caller can update only name/domain without wiping them.

UpdateUnitResponse

Field	Type	Label	Description
unit	Unit		unit is the updated unit.

AdminAppointmentState

AdminAppointmentState distinguishes a live admin (full config powers) from a pending appointment (ZERO powers until the Manager approves — FR-31).

Name	Number	Description
ADMIN_APPOINTMENT_STATE_UNSPECIFIED	0	UNSPECIFIED — zero value; never emitted.
ADMIN_APPOINTMENT_STATE_ACTIVE	1	ACTIVE — role=admin membership written; full config powers.
ADMIN_APPOINTMENT_STATE_PENDING	2	PENDING — appointment awaiting Manager approval; ZERO powers (FR-31).

ConflictPolicy

ConflictPolicy decides how MergeUnits resolves child-name collisions when two children of source + target share a name.

Name	Number	Description
CONFLICT_POLICY_UNSPECIFIED	0	CONFLICT_POLICY_UNSPECIFIED is the zero value; the server treats it as RENAME so callers that forget to set it get the safe behaviour.
CONFLICT_POLICY_RENAME	1	CONFLICT_POLICY_RENAME appends a suffix to the moved child's name (e.g. " (merged)") so both rows survive. Default behaviour.
CONFLICT_POLICY_SKIP	2	CONFLICT_POLICY_SKIP leaves the moved child under source (it is NOT moved to target) so the existing target child wins. The source child is soft-deleted along with the source unit at the end of the merge.
CONFLICT_POLICY_OVERWRITE	3	CONFLICT_POLICY_OVERWRITE soft-deletes the existing target child before the moved child takes its place. The overwritten child's descendants are also soft-deleted (cascade via existing trigger semantics — this is the destructive option).

GovernedOpStatus

GovernedOpStatus is the lifecycle state of a governed unit op (relation / Manager reassign / admin appointment).

Name	Number	Description
GOVERNED_OP_STATUS_UNSPECIFIED	0	UNSPECIFIED — zero value; never emitted.
GOVERNED_OP_STATUS_APPLIED	1	APPLIED — auto-approved (actor manages both endpoints / is the Manager) and physically published.
GOVERNED_OP_STATUS_PENDING_APPROVAL	2	PENDING_APPROVAL — a resource-scoped approval was opened; the physical write is deferred to PublishGovernedUnitOp once granted.
GOVERNED_OP_STATUS_REJECTED	3	REJECTED — the op was denied or its approval expired/denied.

OfferKind

OfferKind is the capability axis of a cross-cutting offer.

Name	Number	Description
OFFER_KIND_UNSPECIFIED	0	UNSPECIFIED — zero value; never emitted.
OFFER_KIND_TOOL	1	TOOL — an org_unit_tools attachment.
OFFER_KIND_MCP	2	MCP — an mcp_servers attachment.
OFFER_KIND_KNOWLEDGE	3	KNOWLEDGE — a knowledge_source_units attachment.

ProvenanceVia

ProvenanceVia is the inheritance edge an item travelled to reach the resolved context: a HOME-chain (parent_id) edge or a cross-cutting RELATION edge.

Name	Number	Description
PROVENANCE_VIA_UNSPECIFIED	0	UNSPECIFIED — zero value; never emitted.
PROVENANCE_VIA_HOME	1	HOME — inherited down the active team's HOME (parent_id) chain.
PROVENANCE_VIA_RELATION	2	RELATION — crossed an additional-parent (unit_relations) edge.

OrgUnitService

OrgUnitService manages the flexible org_units tree and memberships.

--- Unit CRUD ---

Method Name	Request Type	Response Type	Description
CreateUnit	CreateUnitRequest	CreateUnitResponse	CreateUnit creates a new org_unit under an optional parent. Triggers compute ancestor_path/depth and guard against cycles. Requires pillars.edit (unit_type=pillar) or teams.edit (unit_type=team) — equivalently, org_units.create once the RBAC seed flips catalog.
GetUnit	GetUnitRequest	GetUnitResponse	GetUnit retrieves a single unit with its ancestor_path, depth, and direct_child_count (helper for UI rendering).
UpdateUnit	UpdateUnitRequest	UpdateUnitResponse	UpdateUnit renames or retypes a unit. Does NOT change parent; use MoveUnit for reparenting so trigger cascade semantics stay explicit.
DeleteUnit	DeleteUnitRequest	DeleteUnitResponse	DeleteUnit soft-deletes a unit. When reparent_children=true direct children are moved up to the deleted unit's parent; otherwise the RPC returns FAILED_PRECONDITION if any direct children exist.
ListUnits	ListUnitsRequest	ListUnitsResponse	ListUnits returns paginated units for the org, optionally filtered by parent_id or unit_type.
GetTree	GetTreeRequest	GetTreeResponse	GetTree returns a flat, depth-first list of units rooted at root_id (or org roots when empty). max_depth=0 means unlimited.
MoveUnit	MoveUnitRequest	MoveUnitResponse	MoveUnit reparents a unit. Descendants' ancestor_path and depth are recomputed in the same transaction by migration 060's AFTER trigger. Returns INVALID_ARGUMENT when the move would create a cycle.
MergeUnits	MergeUnitsRequest	MergeUnitsResponse	MergeUnits atomically folds source_id into target_id: every active child of source becomes a child of target (subject to conflict_policy for name collisions), every active membership of source moves to target, and source is soft-deleted. The operation runs inside the gateway-supplied scope tx so partial failure rolls back atomically. Both units must belong to the caller's org. GAP-V2-8 (#1064).
SplitUnit	SplitUnitRequest	SplitUnitResponse	SplitUnit creates a new sibling unit under the same parent as source_id, then moves the requested member_ids from source to the new unit. The remainder stays in source. The operation runs in a single tx. The new unit inherits source's unit_type. GAP-V2-9 (#1064).
AssignMember	AssignMemberRequest	AssignMemberResponse	AssignMember upserts a member→unit membership with role (member
RemoveMember	RemoveMemberRequest	RemoveMemberResponse	RemoveMember removes a member from a unit. Idempotent — returns removed=false when no membership existed.
ListMembershipsForMember	ListMembershipsForMemberRequest	ListMembershipsForMemberResponse	ListMembershipsForMember returns every unit a member belongs to, including the role in that unit.
ListMembershipsForUnit	ListMembershipsForUnitRequest	ListMembershipsForUnitResponse	ListMembershipsForUnit returns every member assigned to a unit.
AttachTool	AttachToolRequest	AttachToolResponse	AttachTool attaches a tool to an org_unit with a visibility mode. Configure-time subset validation: if an ancestor has the same tool attached with visibility=inherit_down and a more-restrictive config, the RPC returns INVALID_ARGUMENT.
DetachTool	DetachToolRequest	DetachToolResponse	DetachTool soft-deletes a (unit, tool) attachment.
ListToolsForUnit	ListToolsForUnitRequest	ListToolsForUnitResponse	ListToolsForUnit returns the tool attachments configured directly on a unit (no inheritance resolution).
ListToolsForMember	ListToolsForMemberRequest	ListToolsForMemberResponse	ListToolsForMember returns the effective tool set visible to a member: direct ∪ ancestor-inherit_down ∪ sibling-shared_siblings
RequestToolOverride	RequestToolOverrideRequest	RequestToolOverrideResponse	RequestToolOverride opens a tool_config_conflicts row asking an approver to allow a child unit's desired config that violates the parent's inherit_down subset rule.
ResolveToolOverride	ResolveToolOverrideRequest	ResolveToolOverrideResponse	ResolveToolOverride approves or rejects an override request.
SetTeamModelAllowlist	SetTeamModelAllowlistRequest	SetTeamModelAllowlistResponse	SetTeamModelAllowlist replaces the full set of allowed model_ids for a team (unit_type=team). Passing an empty model_ids list clears the allowlist (which means "allow all models the tenant has providers for" — the BYOA AI gateway enforces the provider side separately).

Requires team_models.manage with ScopeOrgUnit of the unit. | | GetTeamModelAllowlist | GetTeamModelAllowlistRequest | GetTeamModelAllowlistResponse | GetTeamModelAllowlist returns the current allowlist for a team. An empty model_ids list means "no restriction — allow all". | | ListTeamModels | ListTeamModelsRequest | ListTeamModelsResponse | ListTeamModels returns the EFFECTIVE, selectable model set for a team — the source of truth the "Create Workflow" wizard's model picker binds to (#2008). It resolves the team's status='approved' allowlist and enriches each id with provider/display_name from the platform seed catalogue. An EMPTY approved set means "no restriction", so it falls back to the whole tenant provider-backed catalogue — identical semantics to the AI Gateway's Allowed() check (migrations 072/129). is_default marks the entry that matches the agent-configuration default model. Read-only; requires teams.view (a team-scoped read, no more sensitive than GetTeamModelAllowlist). | | ListPendingModelAllowlistEntries | ListPendingModelAllowlistEntriesRequest | ListPendingModelAllowlistEntriesResponse | ListPendingModelAllowlistEntries returns the pending model-allowlist entries across every team the given Manager manages (org_units.manager_member_id) — the Manager's model-approval inbox. RLS scopes to the caller's org. Mirrors ListPendingMCPServerBindings. | | ApproveModelAllowlistEntry | ApproveModelAllowlistEntryRequest | ApproveModelAllowlistEntryResponse | ApproveModelAllowlistEntry transitions a pending entry to approved, making the model routable by the AI Gateway. ONLY the entry's team Manager may call it. Mirrors ApproveMCPServerBinding. | | DenyModelAllowlistEntry | DenyModelAllowlistEntryRequest | DenyModelAllowlistEntryResponse | DenyModelAllowlistEntry transitions a pending entry to denied (with an optional reason). ONLY the entry's team Manager may call it; the model stays non-routable. Mirrors DenyMCPServerBinding. | | RouteTeam | RouteTeamRequest | RouteTeamResponse | RouteTeam maps a Task's intent tags to the best-fit team org-unit using deterministic domain/capability metadata only (no LLM, no fuzzy match). Precedence: a team whose domain equals one of the intent tags beats a team matched only on capability overlap; among equals, higher overlap wins; ties break on the lexicographically smallest unit id. Returns NOT_FOUND when no team matches and INVALID_ARGUMENT when no intent tags are supplied. Read-only; requires teams.view. | | AddUnitRelation | AddUnitRelationRequest | AddUnitRelationResponse | AddUnitRelation proposes an additional-parent edge (parent → child) in the combined org graph. Validate-time it rejects an edge that would create a cycle in the COMBINED (home parent_id ∪ unit_relations) up-graph (INVALID_ARGUMENT + the offending path). When the acting member manages BOTH endpoint teams it auto-approves and publishes the edge immediately (status APPLIED); otherwise it opens a two-Manager resource-scoped approval (action_type team_relation_change) and returns PENDING_APPROVAL with a draft_id + approval_id. Requires org_units.update. | | RemoveUnitRelation | RemoveUnitRelationRequest | RemoveUnitRelationResponse | RemoveUnitRelation detaches an existing edge from either endpoint (FR-4), via the same two-Manager governance as AddUnitRelation. | | ListUnitRelations | ListUnitRelationsRequest | ListUnitRelationsResponse | ListUnitRelations returns a unit's active additional-parent edges: parents are edges where the unit is the child, children where it is the parent. Read-only; requires org_units.view. | | PublishGovernedUnitOp | PublishGovernedUnitOpRequest | PublishGovernedUnitOpResponse | PublishGovernedUnitOp resumes a pending governed unit op (relate / unrelate / reassign_manager / appoint_admin) once its approval is granted, applying the physical write inside the per-org advisory-locked version transaction. Re-entrant (pull-based resume): a no-op on an already-published draft. | | SetHomeParent | SetHomeParentRequest | SetHomeParentResponse | SetHomeParent reparents a unit's HOME parent (org_units.parent_id). Unlike MoveUnit it also runs the service-level COMBINED-graph cycle check so a reparent that closes a loop THROUGH a relation edge is rejected at validate time (the migration-060 trigger only walks the home tree). Requires org_units.update. | | GetUnitManager | GetUnitManagerRequest | GetUnitManagerResponse | GetUnitManager returns a unit's Manager member id (empty when unassigned). Read-only; requires org_units.view. | | SetUnitManager | SetUnitManagerRequest | SetUnitManagerResponse | SetUnitManager reassigns a unit's Manager. Governed (approval + audit): auto-applies when the actor is the current Manager, otherwise opens a team_manager_reassign approval. Requires org_units.update. | | AppointUnitAdmin | AppointUnitAdminRequest | AppointUnitAdminResponse | AppointUnitAdmin appoints an additional admin. FR-30 privilege validation: the candidate's identity clearance MUST meet the capability-floor matrix (team_edit, knowledge_edit, mcp_configure, tool_config); a failed check is rejected FAILED_PRECONDITION with the missing-privileges list and NO approval is opened. A qualified candidate is appointed with ZERO powers (PENDING) until the Manager approves — auto-applied (ACTIVE) when the actor IS the Manager. Requires org_units.update. | | ApproveUnitAdmin | ApproveUnitAdminRequest | ApproveUnitAdminResponse | ApproveUnitAdmin is the Manager granting a pending admin appointment, writing the role=admin membership. Requires org_units.update. | | RejectUnitAdmin | RejectUnitAdminRequest | RejectUnitAdminResponse | RejectUnitAdmin declines a pending admin appointment. Requires org_units.update. | | RemoveUnitAdmin | RemoveUnitAdminRequest | RemoveUnitAdminResponse | RemoveUnitAdmin removes an active additional admin. Requires org_units.update. | | ListUnitAdmins | ListUnitAdminsRequest | ListUnitAdminsResponse | ListUnitAdmins returns a unit's Manager plus its admins (ACTIVE + PENDING). Read-only; requires org_units.view. | | MarkShareable | MarkShareableRequest | MarkShareableResponse | MarkShareable flips the shareable flag on a unit's tool / MCP / knowledge attachment, offering it cross-cuttingly. Requires org_units.update. | | ListOffers | ListOffersRequest | ListOffersResponse | ListOffers lists shareable items offered by OTHER units for the given kind (candidate offers a unit may accept), each flagged whether already accepted. Read-only; requires org_units.view. | | AcceptOffer | AcceptOfferRequest | AcceptOfferResponse | AcceptOffer accepts a cross-cutting offer, writing unit_accepted_offers so the resolver (W1-B) surfaces the item for the accepting unit. Requires org_units.update. | | DeclineOffer | DeclineOfferRequest | DeclineOfferResponse | DeclineOffer soft-deletes a previously accepted offer. Requires org_units.update. | | ResolveEffectiveConfig | ResolveEffectiveConfigRequest | ResolveEffectiveConfigResponse | ResolveEffectiveConfig resolves the effective per-axis config for ONE team (unit_id treated as the active team): guardrails (PUSH, most-restrictive), tools/MCP/knowledge (home inherit + accepted cross offers), every item carrying provenance. Read-only; requires org_units.view. | | ResolveEffectiveConfigForMember | ResolveEffectiveConfigForMemberRequest | ResolveEffectiveConfigForMemberResponse | ResolveEffectiveConfigForMember resolves effective config for a member in the context of ONE active team (active_unit_id) — the live execution scope for an agent homed in that team (FR-12/FR-24). Read-only; requires members.view. | | AdminResolveAllTeamsUnion | AdminResolveAllTeamsUnionRequest | AdminResolveAllTeamsUnionResponse | AdminResolveAllTeamsUnion is the FR-15 ADMIN/AUDIT-ONLY union across EVERY team the member belongs to — "everything this member could ever touch". It is NEVER the live execution scope; do NOT use it to build an agent's runtime config (use ResolveEffectiveConfigForMember). Read-only; requires members.view. |

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)