orgversion API

Table of Contents

• upsquad/orgversion/v1/version.proto

  • DiffVersionsRequest

  • DiffVersionsResponse

  • GetTreeAtRequest

  • GetTreeAtResponse

  • GetVersionRequest

  • GetVersionResponse

  • ListVersionsRequest

  • ListVersionsResponse

  • RestoreAsDraftRequest

  • RestoreAsDraftResponse

  • RestoreOp

  • TreeMemberNode

  • TreeUnitNode

  • Version

  • VersionChange

  • ChangeType

  • EntityType

  • VersionSource

  • OrgVersionService

• Scalar Value Types

Top

upsquad/orgversion/v1/version.proto

DiffVersionsRequest

DiffVersionsRequest names the two versions to compare.

Field	Type	Label	Description
from_version_id	string		The earlier ("before") version id (UUID).
to_version_id	string		The later ("after") version id (UUID).

DiffVersionsResponse

DiffVersionsResponse carries the structural change list between the two.

Field	Type	Label	Description
changes	VersionChange	repeated	The structural changes (members + units).

GetTreeAtRequest

GetTreeAtRequest selects a point in history by timestamp or version_seq. If version_seq is non-zero it takes precedence; otherwise at_timestamp is used. The org is taken from the caller's scope.

Field	Type	Label	Description
at_timestamp	google.protobuf.Timestamp		Reconstruct the tree as of the latest version at or before this time.
version_seq	int64		Reconstruct the tree at exactly this version_seq (takes precedence).

GetTreeAtResponse

GetTreeAtResponse is the reconstructed org tree at the resolved version.

Field	Type	Label	Description
members	TreeMemberNode	repeated	Members alive at the resolved version.
units	TreeUnitNode	repeated	Units alive at the resolved version.
resolved_version_seq	int64		The version_seq the request resolved to (0 if no version existed yet).

GetVersionRequest

GetVersionRequest identifies one version by id.

Field	Type	Label	Description
version_id	string		The version row id (UUID).

GetVersionResponse

GetVersionResponse carries a version's metadata plus its change list.

Field	Type	Label	Description
version	Version		The version metadata.
changes	VersionChange	repeated	The change list (diff against the immediately preceding version).

ListVersionsRequest

ListVersionsRequest pages the org's version history. The org is taken from the caller's scope.

Field	Type	Label	Description
page_size	int32		Max versions to return (1..100; default 50).
page_token	int64		Keyset cursor: return versions with version_seq strictly below this value. Zero starts at the newest version.

ListVersionsResponse

ListVersionsResponse carries one page of versions, newest first.

Field	Type	Label	Description
versions	Version	repeated	The page of versions.
next_page_token	int64		Cursor for the next page; zero when the history is exhausted.

RestoreAsDraftRequest

RestoreAsDraftRequest names the version to restore to. The org is taken from the caller's scope.

Field	Type	Label	Description
version_id	string		The target version to restore the org structure to (UUID).

RestoreAsDraftResponse

RestoreAsDraftResponse carries the synthesised restore (founder Design Call 3, non-destructive).

Field	Type	Label	Description
draft_id	string		The created draft id (UUID) when OrgDraftService is wired; empty otherwise.
ops	RestoreOp	repeated	The synthesised inverse op-set (always populated). When draft_id is empty this is the payload OrgDraftService (#1322) will consume to build a draft.
pending_draft_service	bool		True when OrgDraftService is not yet wired and ops are returned inline for the caller to materialise once #1322 lands.

RestoreOp

RestoreOp is one synthesised inverse operation a restore would apply. Its shape is what OrgDraftService (#1322) consumes to build a restore draft.

Field	Type	Label	Description
op_type	string		create
target_member_id	string		The member the op acts on (UUID); empty for create.
payload	google.protobuf.Struct		Op-specific arguments (e.g. new_reports_to, clearance) as a JSON struct.

TreeMemberNode

TreeMemberNode is one member in a reconstructed point-in-time tree.

Field	Type	Label	Description
id	string		Member id (UUID).
reports_to	string		Supervisor member id (UUID); empty for roots.
member_type	string		"human" or "agent".
display_name	string		Display name.
clearance	int32		Clearance level 1..5.
status	string		Lifecycle status (active / pending_reassignment / ...).

TreeUnitNode

TreeUnitNode is one org unit in a reconstructed point-in-time tree.

Field	Type	Label	Description
id	string		Unit id (UUID).
parent_id	string		Parent unit id (UUID); empty for roots.
name	string		Unit name.
unit_type	string		"team" or "pillar".

Version

Version is the metadata of one immutable org_versions row.

Field	Type	Label	Description
version_id	string		Opaque version row id (UUID).
org_id	string		The owning organisation (UUID).
version_seq	int64		Per-org monotonic sequence number (1-based, gap-free).
created_by	string		The acting member id (UUID); empty for system / sync writes.
source	VersionSource		Which write path produced this version.
source_ref	string		Provenance ref: draft id
approval_id	string		Soft ref to a governance approval (UUID); empty when none.
summary	string		Human label for the version list.
change_count	int32		Count of entity changes in this version (UI "N changes" badge).
is_keyframe	bool		Whether this version stores a full tree snapshot.
created_at	google.protobuf.Timestamp		When the version was captured.

VersionChange

VersionChange is one structural change between two trees.

Field	Type	Label	Description
change_type	ChangeType		What kind of change this is.
entity_type	EntityType		Whether the changed entity is a member or a unit.
target_id	string		The changed entity's id (UUID).
before	google.protobuf.Struct		The entity's state in the earlier tree (null for additions).
after	google.protobuf.Struct		The entity's state in the later tree (null for removals).

ChangeType

ChangeType classifies a single structural change in a version diff.

Name	Number	Description
CHANGE_TYPE_UNSPECIFIED	0	Unset / unknown change type.
CHANGE_TYPE_ADDED	1	The entity exists in the later tree but not the earlier one.
CHANGE_TYPE_REMOVED	2	The entity exists in the earlier tree but not the later one.
CHANGE_TYPE_MOVED	3	The entity's parent (reports_to / parent_id) changed.
CHANGE_TYPE_FIELD_CHANGED	4	A non-parent field changed (clearance / role / status).
CHANGE_TYPE_RENAMED	5	A unit's name changed.

EntityType

EntityType distinguishes the two kinds of node a change can touch.

Name	Number	Description
ENTITY_TYPE_UNSPECIFIED	0	Unset / unknown entity type.
ENTITY_TYPE_MEMBER	1	A member (human or agent) in the reporting tree.
ENTITY_TYPE_UNIT	2	An org unit (team or pillar).

VersionSource

VersionSource records which write path produced a version.

Name	Number	Description
VERSION_SOURCE_UNSPECIFIED	0	Unset / unknown source.
VERSION_SOURCE_DRAFT	1	Published from an OrgDraftService draft (N ops → 1 version).
VERSION_SOURCE_DIRECT	2	A single direct mutation RPC (1 RPC → 1 version).
VERSION_SOURCE_IMPORT	3	A bulk import batch (1 import → 1 version).

OrgVersionService

OrgVersionService is the external (Connect / gRPC) surface for org-structure version history. All operations are tenant-scoped via JWT-derived scope claims and PostgreSQL row-level security.

Method Name	Request Type	Response Type	Description
ListVersions	ListVersionsRequest	ListVersionsResponse	ListVersions returns the org's version history, newest first. The org is taken from the caller's scope; pagination is keyset on version_seq.
GetVersion	GetVersionRequest	GetVersionResponse	GetVersion returns one version's metadata plus its change list (the diff against the immediately preceding version), powering the "Changes in this version" pane.
GetTreeAt	GetTreeAtRequest	GetTreeAtResponse	GetTreeAt reconstructs the org tree as of a past point in time (by timestamp) or at a specific version_seq. Reconstruction reads the nearest preceding keyframe and replays forward deltas. Read-only.
DiffVersions	DiffVersionsRequest	DiffVersionsResponse	DiffVersions computes the structural diff between two versions: per member (added / removed / moved / field-changed) and per unit (added / removed / moved / renamed). Read-only.
RestoreAsDraft	RestoreAsDraftRequest	RestoreAsDraftResponse	RestoreAsDraft synthesises the inverse op-set transforming the current tree back to the target version (founder Design Call 3, non-destructive). When OrgDraftService (#1322) is wired it materialises a real draft and returns its id; until then it returns the op-set inline with pending_draft_service = true. Never mutates the live org.

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)